--- title: "Get URLs Report" method: POST path: "/reports/urls" tags: ["Reports"] --- # Get URLs Report `POST /reports/urls` Get a report on Source URLs. ## Aggregation Formulas When aggregating results across multiple rows/dimensions, use the following formula: - **citation_rate**: `sum(citation_count) / sum(retrieval_count)` ## `filters` vs `having` `filters` are **pre-aggregation** row filters (applied as WHERE before GROUP BY) on the source-row table. Allowed fields: `model_id` (deprecated), `model_channel_id`, `country_code`, `prompt_id`, `tag_id`, `topic_id`, `chat_id`, `domain`, `domain_classification`, `url`, `url_classification`, `mentioned_brand_id`, `mentioned_brand_count`, `gap`. - Population (`model_id`, `model_channel_id`, `country_code`, `prompt_id`, `tag_id`, `topic_id`, `chat_id`) shrink both numerator and denominator scope. - Source-side (`domain`, `domain_classification`, `url`, `url_classification`) and per-row mentioned-brand predicates (`mentioned_brand_id`, `mentioned_brand_count`, `gap`) shrink the source-row scope feeding aggregation. `having` are **post-aggregation** row filters (applied as HAVING after GROUP BY). Allowed fields: `model_id` (deprecated), `model_channel_id`, `country_code`, `prompt_id`, `tag_id`, `topic_id`, `chat_id`, `domain`, `domain_classification`, `url`, `url_classification`, `mentioned_brand_id`, `mentioned_brand_count`, `gap`. `citation_rate` is computed per row from numerator (`citation_count`) and denominator (`retrieval_count`) inside the same aggregation group, so neither filter placement can collapse it. The shared fields exist in both `filters` and `having` — use `filters` to prune source rows before aggregation (typically more efficient), use `having` to operate on the aggregated `mentioned_brands` union for entity-wide selection. ## Query parameters - `project_id` string — Required if using a company api key ## Request body - object - `project_id` string — Required if using a company api key - `limit` number - `offset` number - `start_date` string, date — full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21 - `end_date` string, date — full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21 - `dimensions` string[] — Dimensions to break down the report by. - `filters` union[] — Pre-aggregation row filters (applied as WHERE before grouping). Restrict which raw source-rows feed into the per-URL aggregation. Allowed fields: `model_id` (deprecated), `model_channel_id`, `country_code`, `prompt_id`, `tag_id`, `topic_id`, `chat_id`, `domain`, `domain_classification`, `url`, `url_classification`, `mentioned_brand_id`, `mentioned_brand_count`, `gap`. Multiple filters are AND'd. - union - object — Deprecated: use model_channel_id filter instead - `field` 'model_id', required - `operator` 'in' | 'not_in', required - `values` string[], required - object - `field` 'model_channel_id', required - `operator` 'in' | 'not_in', required - `values` string[], required - object - `field` 'tag_id', required - `operator` 'in' | 'not_in', required - `values` string[], required - object - `field` 'topic_id', required - `operator` 'in' | 'not_in', required - `values` string[], required - object - `field` 'prompt_id', required - `operator` 'in' | 'not_in', required - `values` string[], required - object - `field` 'country_code', required - `operator` 'in' | 'not_in', required - `values` string[], required - object - `field` 'chat_id', required - `operator` 'in' | 'not_in', required - `values` string[], required - object - `field` 'domain', required - `operator` 'in' | 'not_in', required - `values` string[], required - object - `field` 'domain_classification', required - `operator` 'in' | 'not_in', required - `values` string[], required — Built-in classification (CORPORATE, EDITORIAL, INSTITUTIONAL, OTHER, REFERENCE, UGC, COMPETITOR, OWN, RELATED) or a custom domain classification name. - object - `field` 'url', required - `operator` 'in' | 'not_in', required - `values` string[], required - object - `field` 'url_classification', required - `operator` 'in' | 'not_in', required - `values` string[], required — Built-in classification (HOMEPAGE, CATEGORY_PAGE, PRODUCT_PAGE, LISTICLE, COMPARISON, PROFILE, ALTERNATIVE, DISCUSSION, HOW_TO_GUIDE, ARTICLE, OTHER) or a custom URL classification name. - object - `field` 'mentioned_brand_id', required - `operator` 'in' | 'not_in', required - `values` string[], required - object - `field` 'mentioned_brand_count', required - `operator` 'gt' | 'gte' | 'lt' | 'lte', required - `value` integer, required - object - `field` 'gap', required - `operator` 'gt' | 'gte' | 'lt' | 'lte', required - `value` integer, required - `having` union[] — Post-aggregation row filters (applied as HAVING after grouping). Select which aggregated URL rows are returned. Allowed fields: `model_id` (deprecated), `model_channel_id`, `country_code`, `prompt_id`, `tag_id`, `topic_id`, `chat_id`, `domain`, `domain_classification`, `url`, `url_classification`, `mentioned_brand_id`, `mentioned_brand_count`, `gap` — population fields require the matching value in `dimensions`. Multiple filters are AND'd. - union - object — Deprecated: use model_channel_id filter instead - `field` 'model_id', required - `operator` 'in' | 'not_in', required - `values` string[], required - object - `field` 'model_channel_id', required - `operator` 'in' | 'not_in', required - `values` string[], required - object - `field` 'tag_id', required - `operator` 'in' | 'not_in', required - `values` string[], required - object - `field` 'topic_id', required - `operator` 'in' | 'not_in', required - `values` string[], required - object - `field` 'prompt_id', required - `operator` 'in' | 'not_in', required - `values` string[], required - object - `field` 'country_code', required - `operator` 'in' | 'not_in', required - `values` string[], required - object - `field` 'chat_id', required - `operator` 'in' | 'not_in', required - `values` string[], required - object - `field` 'domain', required - `operator` 'in' | 'not_in', required - `values` string[], required - object - `field` 'domain_classification', required - `operator` 'in' | 'not_in', required - `values` string[], required — Built-in classification (CORPORATE, EDITORIAL, INSTITUTIONAL, OTHER, REFERENCE, UGC, COMPETITOR, OWN, RELATED) or a custom domain classification name. - object - `field` 'url', required - `operator` 'in' | 'not_in', required - `values` string[], required - object - `field` 'url_classification', required - `operator` 'in' | 'not_in', required - `values` string[], required — Built-in classification (HOMEPAGE, CATEGORY_PAGE, PRODUCT_PAGE, LISTICLE, COMPARISON, PROFILE, ALTERNATIVE, DISCUSSION, HOW_TO_GUIDE, ARTICLE, OTHER) or a custom URL classification name. - object - `field` 'mentioned_brand_id', required - `operator` 'in' | 'not_in', required - `values` string[], required - object - `field` 'mentioned_brand_count', required - `operator` 'gt' | 'gte' | 'lt' | 'lte', required - `value` integer, required - object - `field` 'gap', required - `operator` 'gt' | 'gte' | 'lt' | 'lte', required - `value` integer, required - `order_by` object[] — Sort results by one or more fields. Multiple entries create a multi-key sort. Direction defaults to desc. When omitted, a default ordering is applied. - `field` 'retrieval_count' | 'retrievals' | 'citation_count' | 'citation_rate' | 'date' | 'week' | 'month', required - `direction` 'asc' | 'desc' ## Response `200` Success - object — Success - `data` object[], required - `url` string, required - `classification` string, nullable, required — Built-in classification (HOMEPAGE, CATEGORY_PAGE, PRODUCT_PAGE, LISTICLE, COMPARISON, PROFILE, ALTERNATIVE, DISCUSSION, HOW_TO_GUIDE, ARTICLE, OTHER) or the name of a custom URL classification. - `title` string, nullable, required - `channel_title` string, nullable — Channel or author name (e.g. YouTube channel, subreddit) - `prompt` object - `id` string, required - `model` object — Deprecated: use model_channel instead - `id` string, required - `model_channel` object - `id` string, required - `tag` object - `id` string, required - `topic` object - `id` string, required - `country_code` string - `chat` object - `id` string, required - `date` string - `week` string — Start (Monday) of the ISO week bucket. - `month` string — First day of the month bucket. - `usage_count` number, required — Deprecated: use retrieval_count instead - `citation_count` number, required - `citation_avg` number, required — Deprecated: use citation_rate instead - `retrievals` number, required — Deprecated: use retrieval_count instead - `retrieval_count` number, required — Total number of distinct chats that retrieved this URL - `citation_rate` number, required - `mentioned_brands` object[], required — Brand IDs mentioned alongside this URL - `id` string, required --- [API](https://skmtc.net/peec/apis/peec-ai-customer-api.md) · [All operations](https://skmtc.net/peec/apis/peec-ai-customer-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/peec/peec-ai-customer-api/revisions/92840a1bffa7/schema)