> ## Documentation Index > Fetch the complete documentation index at: https://docs.trychainshift.ai/llms.txt > Use this file to discover all available pages before exploring further. # Cited URL ranking > > **[BETA]** This is a beta API. The response spec may change without notice. Aggregates the sources cited in answers at the URL level. - `urls` is a ranking that contains only the top `limit` entries by citation count in descending order. It is not paginated. - The total citation count across the queried scope (`totalCitations`) is returned as well. - When `domains` is specified, only URLs under those domains are included. This lets you check whether your own pages were cited even if they fall outside the top `limit`. - The matching basis for `domains` and the notation of each item's `domain` field follow `groupBy`, so you can drill down by passing the values you saw in domain statistics (`groupBy=subdomain`) as they are. ### Errors | HTTP | Code | Description | | --- | --- | --- | | 400 | `COMMON_VALIDATION` | • Both runIDs and promptIDs missing • runIDs count (5) or promptIDs count (10) exceeded • limit out of range (1 to 200) • domains filter count (50) or length (253 characters) exceeded • Unsupported groupBy, model, or include value | | 400 | `COMMON_BINDING` | Invalid runIDs or promptIDs format (`PLATFORM_INVALID_ID` in details) | | 401 | `COMMON_UNAUTHORIZED` | API key or access token is missing or invalid | | 402 | `INSUFFICIENT_CREDITS` | The organization's credit balance is lower than the unit price of this request | | 429 | `PLATFORM_RATE_LIMIT_EXCEEDED` | Rate limit exceeded. Wait for the number of seconds in the `Retry-After` header, then retry | | 500 | — | Internal server error. Returns `message` and `requestID` without a `code` | See the [Analyzing with statistics](https://docs.trychainshift.ai/en/guides/analytics.md#cited-url-ranking) guide for real examples (including the actual quoted sentences) and interpretation. ## OpenAPI ````yaml openapi.en.json GET /v1beta/platform/sources/statistics/urls openapi: 3.1.0 info: description: >- Platform API for external partners. Uses organization API key based authentication. ### Common request limits - The request body size is limited to 2MiB. Exceeding it returns 413 with the `COMMON_REQUEST_BODY_TOO_LARGE` code. - Array parameters and string fields have per-endpoint count and length limits. The limits are stated in each field or parameter description, and violating them returns 400 with the `COMMON_VALIDATION` code. ### Error responses The error response body always has the same three fields regardless of the status code. | Field | Type | Meaning | | --- | --- | --- | | `code` | string | A fixed identifier for the error type. This is the only value clients should branch on. The codes each endpoint returns are listed in the "Errors" table of that API. | | `message` | string | A human-readable, one-line summary of the whole error. There is always exactly one. | | `details` | array of strings | Individual reasons that do not fit in the single `message` line. Even a single reason is returned as an array of length 1, and the field is omitted when there is nothing to include. | - `details` is an array in every error. It is never returned as a string or an object, so no type-based branching is needed. - The wording of `details` is not a fixed contract. Use it only for display and debugging, and do not parse the strings to branch. Branch on `code` instead. - `details` is the only field that carries multiple reasons. There is no `messages` field in the response. - On validation failure (`COMMON_VALIDATION`), `details` contains one `"field: reason"` line per violated field. Example: `{"code":"COMMON_VALIDATION","message":"Data validation failed","details":["keywords: up to 100 items can be entered"]}` - `message` defaults to Korean and is returned in English when you send `Accept-Language: en`. `details` follows the same rule when it carries per-field reasons such as validation failures, but errors that include raw text for diagnostic purposes may contain wording in a language other than the requested one. - Only 500 has a different shape. It returns `message` and a `requestID` to reference when contacting support, without `code`. title: Platform API version: '1.0' servers: - url: https://platform-api.trychainshift.ai/api security: [] tags: - description: >- The top-level account unit that API keys belong to. Retrieve the organization's basic information. name: Organization - description: >- A target brand whose exposure in AI services is monitored. Provides brand registration, retrieval, update, and deletion. name: Brand - description: >- Keyword intelligence for analyzing brands and markets. Provides Google and Naver search metrics, related and autocomplete keyword lookups, and site URL based keyword analysis. name: Keyword (Beta) - description: >- A group that organizes prompts by purpose. Provides create, get, update, and delete operations for prompt sets. name: PromptSet - description: >- A sentence-level unit of a query sent to an AI service. Provides prompt create, get, update, and delete, plus bulk creation. name: Prompt - description: AI service models used for prompt runs. Lists the supported models. name: Model - description: The region used to run prompts. Retrieves the list of supported regions. name: Region - description: >- The unit of work that actually runs prompts against AI services. Provides prompt run requests and retrieval of progress status and lists. name: Run - description: >- An AI service response collected by a run. Retrieves answers including sources and search queries. name: Answer - description: >- Statistics on the sources cited in answers, at the domain and URL level. Retrieve the citation summary and per-domain and per-URL citation statistics. name: SourceStatistics (Beta) - description: >- Statistics on tokens (Kiwi nouns) in answer bodies. Retrieves a ranking of the most frequent tokens and the tokens near a specific word. name: AnswerStatistics (Beta) - description: >- Statistics on the search queries (fan-outs) the AI actually issued while generating answers. Retrieves a ranking of search queries by occurrence count. name: FanoutStatistics (Beta) - description: >- An auxiliary feature that identifies proper nouns in text. Provides proper noun extraction. name: ProperNoun (Beta) - description: >- Organization credit balance and Platform API billing information. Retrieves the current credit balance. name: Credit externalDocs: description: '' url: '' paths: /v1beta/platform/sources/statistics/urls: get: tags: - SourceStatistics (Beta) summary: Get citation statistics by URL description: >- > **[BETA]** This is a beta API. The response spec may change without notice. Aggregates the sources cited in answers at the URL level. - `urls` is a ranking that contains only the top `limit` entries by citation count in descending order. It is not paginated. - The total citation count across the queried scope (`totalCitations`) is returned as well. - When `domains` is specified, only URLs under those domains are included. This lets you check whether your own pages were cited even if they fall outside the top `limit`. - The matching basis for `domains` and the notation of each item's `domain` field follow `groupBy`, so you can drill down by passing the values you saw in domain statistics (`groupBy=subdomain`) as they are. ### Errors | HTTP | Code | Description | | --- | --- | --- | | 400 | `COMMON_VALIDATION` | • Both runIDs and promptIDs missing • runIDs count (5) or promptIDs count (10) exceeded • limit out of range (1 to 200) • domains filter count (50) or length (253 characters) exceeded • Unsupported groupBy, model, or include value | | 400 | `COMMON_BINDING` | Invalid runIDs or promptIDs format (`PLATFORM_INVALID_ID` in details) | | 401 | `COMMON_UNAUTHORIZED` | API key or access token is missing or invalid | | 402 | `INSUFFICIENT_CREDITS` | The organization's credit balance is lower than the unit price of this request | | 429 | `PLATFORM_RATE_LIMIT_EXCEEDED` | Rate limit exceeded. Wait for the number of seconds in the `Retry-After` header, then retry | | 500 | — | Internal server error. Returns `message` and `requestID` without a `code` | operationId: listSourceStatisticsURLs parameters: - description: >- Prompt run filter (IDs issued when the run request was made, repeatable, up to 5; multiple values are combined as a union). At least one of runIDs or promptIDs is required example: S8cqDSjSot67bCK6YtmvHw in: query name: runIDs schema: items: type: string type: array style: form - description: >- Prompt filter (the id from the prompt list or create response, repeatable, up to 10; multiple values are combined as a union). At least one of runIDs or promptIDs is required example: KNUETdAfRhDY9lQTgu9wuw in: query name: promptIDs schema: items: type: string type: array style: form - description: Model filter. Only models retrievable from GET /models are allowed example: CHATGPT in: query name: model schema: enum: - CHATGPT - GOOGLE_OVERVIEW - GOOGLE_AI - PERPLEXITY - GEMINI - NAVER_AI_BRIEFING - NAVER_AI_TAB - CLAUDE - META_MUSE - BAIDU_AI_SEARCH - GROK - BAIDU_AI_TAB - DEEPSEEK type: string - description: >- Domain filter (repeatable, up to 50, each 253 characters or less). Matching follows groupBy example: reddit.com in: query name: domains schema: items: type: string type: array style: form - description: >- Matching axis for the domains filter and notation of each item's domain field (default domain=eTLD+1, subdomain=host including subdomains) example: domain in: query name: groupBy schema: enum: - domain - subdomain type: string - description: >- Additional fields to include. models=per-URL model breakdown, quotes=text fragments cited by the AI (up to 20 per URL, deduplicated), urlVariants=list of original URLs merged into this URL example: quotes in: query name: include schema: items: type: string type: array style: form - description: Number of top URLs to return (default 50, maximum 200) example: 50 in: query name: limit schema: type: integer responses: '200': content: application/json: schema: $ref: '#/components/schemas/domain.ListSourceStatisticsURLsResponse' description: OK '400': content: application/json: schema: $ref: '#/components/schemas/domain.ValidationError' description: >- Both runIDs and promptIDs missing, runIDs count (5) or promptIDs count (10) exceeded, limit out of range (1 to 200), domains filter count (50) or length (253 characters) exceeded, unsupported model or include value '401': content: application/json: schema: $ref: '#/components/schemas/domain.UnauthorizedError' description: API key or access token is missing or invalid '402': content: application/json: schema: $ref: '#/components/schemas/domain.InsufficientCreditsError' description: >- The organization's credit balance is lower than the unit price of this request '429': content: application/json: schema: $ref: '#/components/schemas/domain.RateLimitExceededError' description: >- Rate limit exceeded. Wait the number of seconds in the Retry-After header, then retry '500': content: application/json: schema: $ref: '#/components/schemas/domain.InternalServerError' description: >- Internal server error. Include the requestID in your report so it can be traced security: - OrgAPIKeyAuth: [] components: schemas: domain.ListSourceStatisticsURLsResponse: properties: totalCitations: description: Total citation count within the scope example: 1571 type: integer urls: description: >- URL ranking in descending order of citation count (top limit entries) items: $ref: '#/components/schemas/domain.SourceURLStatisticDTO' type: array uniqueItems: false type: object domain.ValidationError: properties: code: description: Error code example: COMMON_VALIDATION type: string details: description: 'List of reasons per violating field (one "field: reason" per line)' example: - 'limit: must be 100 or less' items: type: string type: array uniqueItems: false message: description: >- Error message (Korean by default, English when Accept-Language: en is specified) example: Data validation failed type: string type: object domain.UnauthorizedError: properties: code: description: Error code example: COMMON_UNAUTHORIZED type: string message: description: >- Error message (Korean by default, English when Accept-Language: en is specified) example: Unauthenticated user type: string type: object domain.InsufficientCreditsError: properties: code: description: Error code example: INSUFFICIENT_CREDITS type: string message: description: >- Error message (Korean by default, English when Accept-Language: en is specified) example: Insufficient credits. type: string type: object domain.RateLimitExceededError: properties: code: description: Error code example: PLATFORM_RATE_LIMIT_EXCEEDED type: string message: description: >- Error message (Korean by default, English when Accept-Language: en is specified) example: Too many requests. Please try again later. type: string type: object domain.InternalServerError: properties: message: description: Error message (not localized) example: Internal Server Error type: string requestID: description: >- Request identifier to reference in support inquiries (same value as the X-Request-Id response header) example: bkZqnHQepkgTOocTvyHWSlHcGzRqQbZk type: string type: object domain.SourceURLStatisticDTO: properties: citationCount: description: Total citation count for this URL example: 14 type: integer domain: description: >- Domain of the URL (in groupBy notation: eTLD+1 by default, including subdomains when subdomain. Empty string if undetermined) example: wikipedia.org type: string models: description: >- Breakdown of citation counts by model (only when include=models, in descending order of citation count) items: $ref: '#/components/schemas/domain.SourceModelStatisticDTO' type: array uniqueItems: false quotes: description: >- Text fragments where the AI cited this URL (only when include=quotes, deduplicated, up to 20 per URL) example: - >- AEO is the practice of optimizing content so that a brand is cited in AI answers items: type: string type: array uniqueItems: false url: description: Cited URL example: https://en.wikipedia.org/wiki/Search_engine_optimization type: string urlVariants: description: >- List of original URLs merged into this URL (included only when include=urlVariants is specified). It always includes the URL itself, and is used to see which URLs were merged when URLs of the same document that differ only in notation, such as mobile addresses (m.) or display-only query parameters, were combined into one. example: - https://en.wikipedia.org/wiki/Search_engine_optimization items: type: string type: array uniqueItems: false type: object domain.SourceModelStatisticDTO: properties: citationCount: description: Citation count in this model example: 69 type: integer model: description: Model example: CHATGPT type: string type: object securitySchemes: OrgAPIKeyAuth: description: '"Enter your organization API key. Example: ''cs_live_xxxx''"' in: header name: API-Key type: apiKey ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.