> ## Documentation Index > Fetch the complete documentation index at: https://docs.heralded.ai/llms.txt > Use this file to discover all available pages before exploring further. # Get Pages > The brand's own pages, most cited over the period first, with their citations, Visits from AI, AI crawler hits and the stored rubric. Visits from AI read the bound GA4 property's 28-day read, with its own coverage dates. AI crawler hits are frozen in the newest pinned weekly scan over crawler_hits_days whole days, 28 ending two days before it started. Each page's funnel uses that window for search, crawl, citation and visit measurements, with null for sources that did not measure the page. ## OpenAPI ````yaml /api-reference/openapi.json get /v1/brands/{brand_id}/pages openapi: 3.1.0 info: description: >- Read-only access to one organization's brands, as the member who created the API key. Each key may make 120 requests a minute. Every error is an RFC 9457 problem (`application/problem+json`) whose `code` names it. summary: Read your brands' AI visibility in Heralded. title: Heralded API version: '1' servers: - url: https://api.heralded.ai security: [] paths: /v1/brands/{brand_id}/pages: get: tags: - v1 summary: Get Pages description: >- The brand's own pages, most cited over the period first, with their citations, Visits from AI, AI crawler hits and the stored rubric. Visits from AI read the bound GA4 property's 28-day read, with its own coverage dates. AI crawler hits are frozen in the newest pinned weekly scan over crawler_hits_days whole days, 28 ending two days before it started. Each page's funnel uses that window for search, crawl, citation and visit measurements, with null for sources that did not measure the page. operationId: listPages parameters: - in: path name: brand_id required: true schema: format: uuid title: Brand Id type: string - in: query name: engine required: false schema: anyOf: - enum: - perplexity - gemini - openai - google_aio - ai_mode - copilot - claude type: string - type: 'null' title: Engine - in: query name: prompt required: false schema: anyOf: - format: uuid type: string - type: 'null' title: Prompt - in: query name: type required: false schema: anyOf: - enum: - organic - brand_specific - competitor_comparison type: string - type: 'null' title: Type - in: query name: intent required: false schema: anyOf: - enum: - educational - problem - comparison - transactional type: string - type: 'null' title: Intent - in: query name: topic required: false schema: anyOf: - format: uuid type: string - type: 'null' title: Topic - in: query name: segment required: false schema: anyOf: - type: string - type: 'null' title: Segment - description: Include only scans up to this completed scan id. in: query name: as_of required: false schema: anyOf: - format: uuid type: string - type: 'null' description: Include only scans up to this completed scan id. title: As Of - in: query name: limit required: false schema: default: 20 maximum: 100 minimum: 1 title: Limit type: integer - in: query name: offset required: false schema: default: 0 minimum: 0 title: Offset type: integer - in: query name: cursor required: false schema: anyOf: - maxLength: 4096 type: string - type: 'null' title: Cursor - in: query name: period required: false schema: default: 1w enum: - 1w - 4w - 12w - all title: Period type: string - in: query name: status required: false schema: anyOf: - enum: - missing - cited - falls_short - ranks_in_search - not_cited type: string - type: 'null' title: Status - in: query name: q required: false schema: anyOf: - maxLength: 200 type: string - type: 'null' title: Q - in: query name: sort required: false schema: default: demand enum: - topic - status - demand - citations - search_clicks - ai_visits - rank title: Sort type: string - in: query name: direction required: false schema: anyOf: - enum: - asc - desc type: string - type: 'null' title: Direction - in: query name: with_menus required: false schema: default: false title: With Menus type: boolean - in: query name: url required: false schema: anyOf: - maxLength: 4096 type: string - type: 'null' title: Url responses: '200': content: application/json: schema: $ref: '#/components/schemas/V1Pages' description: Successful Response '400': content: application/problem+json: example: code: invalid_cursor detail: The cursor is invalid or belongs to a different query. instance: example-request-id status: 400 title: Bad Request type: about:blank schema: $ref: '#/components/schemas/Problem' description: The cursor is invalid or belongs to a different query. '401': content: application/problem+json: example: code: invalid_token detail: >- The Authorization header carries no API key Heralded knows: it is missing, mistyped, revoked or expired. instance: example-request-id status: 401 title: Unauthorized type: about:blank schema: $ref: '#/components/schemas/Problem' description: No API key, or one that is unknown, revoked or expired. headers: WWW-Authenticate: schema: example: Bearer type: string '404': content: application/problem+json: example: code: not_found detail: Nothing here that this API key can read. instance: example-request-id status: 404 title: Not Found type: about:blank schema: $ref: '#/components/schemas/Problem' description: No such brand or answer, or the key's owner cannot read it. '409': content: application/problem+json: example: code: workspace_archived detail: The API key's organization is archived. instance: example-request-id status: 409 title: Conflict type: about:blank schema: $ref: '#/components/schemas/Problem' description: The API key's organization is archived. '422': content: application/problem+json: example: code: invalid_request detail: The request's parameters are invalid; `errors` names each one. errors: - loc: - query - limit msg: Input should be less than or equal to 100 type: less_than_equal instance: example-request-id status: 422 title: Unprocessable Content type: about:blank schema: $ref: '#/components/schemas/ValidationProblem' description: A path or query parameter is invalid. '429': content: application/problem+json: example: code: rate_limited detail: >- This caller is past its requests for the minute. Retry after the seconds in Retry-After. instance: example-request-id rate_limit: limit: 120 remaining: 0 reset: 60 window: 60 status: 429 title: Too Many Requests type: about:blank schema: $ref: '#/components/schemas/RateLimitProblem' description: The API key made more than 120 requests in the minute. headers: Retry-After: description: Seconds until the key may call again. schema: example: 60 type: integer security: - apiKey: [] components: schemas: V1Pages: description: The brand's own pages, most cited in the period first. properties: coverage: anyOf: - $ref: '#/components/schemas/V1VisitCoverage' - type: 'null' crawler_hits_days: title: Crawler Hits Days type: integer limit: title: Limit type: integer meta: $ref: '#/components/schemas/Meta' description: Normalized query and newest included scan. next_cursor: anyOf: - type: string - type: 'null' description: >- Pass as cursor with the same query to read the next page; null at the end. title: Next Cursor offset: title: Offset type: integer pages: items: $ref: '#/components/schemas/V1OwnedPage' title: Pages type: array period: $ref: '#/components/schemas/V1Period' resolved_page_id: anyOf: - format: uuid type: string - type: 'null' title: Resolved Page Id total: title: Total type: integer required: - meta - next_cursor - total - limit - offset - resolved_page_id - period - coverage - crawler_hits_days - pages title: V1Pages type: object Problem: description: |- An RFC 9457 problem. `type` is always `about:blank`, so `title` is the status's name, and `code` is what a client branches on. properties: code: title: Code type: string detail: title: Detail type: string instance: default: '' title: Instance type: string status: title: Status type: integer title: title: Title type: string type: const: about:blank default: about:blank title: Type type: string required: - type - title - status - detail - code - instance title: Problem type: object ValidationProblem: properties: code: title: Code type: string detail: title: Detail type: string errors: items: $ref: '#/components/schemas/ValidationIssue' title: Errors type: array instance: default: '' title: Instance type: string status: title: Status type: integer title: title: Title type: string type: const: about:blank default: about:blank title: Type type: string required: - type - title - status - detail - code - instance - errors title: ValidationProblem type: object RateLimitProblem: properties: code: title: Code type: string detail: title: Detail type: string instance: default: '' title: Instance type: string rate_limit: $ref: '#/components/schemas/RateLimitValues' status: title: Status type: integer title: title: Title type: string type: const: about:blank default: about:blank title: Type type: string required: - type - title - status - detail - code - instance - rate_limit title: RateLimitProblem type: object V1VisitCoverage: properties: end: format: date title: End type: string start: format: date title: Start type: string required: - start - end title: V1VisitCoverage type: object Meta: properties: data_as_of: anyOf: - $ref: '#/components/schemas/DataAsOf' - type: 'null' query: additionalProperties: $ref: '#/components/schemas/JsonValue' title: Query type: object required: - query - data_as_of title: Meta type: object V1OwnedPage: properties: ai_visits: anyOf: - type: integer - type: 'null' description: >- Sessions GA4 attributes to AI assistants over coverage, a floor. Null without a complete read covering this page. title: Ai Visits citations: anyOf: - type: integer - type: 'null' description: >- Citations in the period's counted answers. Null where a weekly scan it covers could not keep all its citations. title: Citations crawler_bots: description: The crawlers behind crawler_hits. items: $ref: '#/components/schemas/V1CrawlerBot' title: Crawler Bots type: array crawler_hits: anyOf: - type: integer - type: 'null' description: >- Served requests from all listed bots, frozen in the newest pinned weekly scan over crawler_hits_days: 28 whole days ending two days before it started. Plugin counts are a floor. Null without a recorded measurement covering the page. title: Crawler Hits funnel: $ref: '#/components/schemas/PageFunnel' id: format: uuid title: Id type: string page_type: title: Page Type type: string prompts: anyOf: - type: integer - type: 'null' description: >- Tracked prompts an answer cited the page on. Null where a weekly scan it covers could not keep all its citations. title: Prompts rubric: anyOf: - $ref: '#/components/schemas/V1PageRubric' - type: 'null' description: Null on a page the rubric does not audit, such as a legal page. title: anyOf: - type: string - type: 'null' title: Title url: title: Url type: string required: - funnel - id - url - title - page_type - citations - prompts - ai_visits - crawler_hits - crawler_bots - rubric title: V1OwnedPage type: object V1Period: properties: excluded_reports: title: Excluded Reports type: integer first_answer_at: anyOf: - format: date-time type: string - type: 'null' title: First Answer At last_answer_at: anyOf: - format: date-time type: string - type: 'null' title: Last Answer At preset: enum: - 1w - 4w - 12w - all title: Preset type: string reports: title: Reports type: integer required: - preset - reports - first_answer_at - last_answer_at - excluded_reports title: V1Period type: object ValidationIssue: properties: loc: items: anyOf: - type: string - type: integer title: Loc type: array msg: title: Msg type: string type: title: Type type: string required: - loc - msg - type title: ValidationIssue type: object RateLimitValues: properties: limit: title: Limit type: integer remaining: title: Remaining type: integer reset: title: Reset type: integer window: title: Window type: integer required: - limit - window - remaining - reset title: RateLimitValues type: object DataAsOf: properties: completed_at: format: date-time title: Completed At type: string id: format: uuid title: Id type: string required: - id - completed_at title: DataAsOf type: object JsonValue: {} V1CrawlerBot: properties: bot: title: Bot type: string category: anyOf: - enum: - training - ai_search - user_fetch - search_engine type: string - type: 'null' title: Category hits: title: Hits type: integer operator: anyOf: - type: string - type: 'null' title: Operator required: - bot - operator - hits - category title: V1CrawlerBot type: object PageFunnel: properties: ai_visits: anyOf: - type: integer - type: 'null' description: >- Visits from AI attributed by GA4 in window, a floor because visits often carry no referrer. Null without a complete read of the current property covering this page for that window. title: Ai Visits blocked: anyOf: - type: integer - type: 'null' description: >- Blocked requests from AI categories in window, across all verification states. Plugin counts are a floor. Null when unmeasured. title: Blocked cited: anyOf: - type: integer - type: 'null' description: >- Frozen citations with default filters from weekly scans completed inside window. Null without scans or with incomplete citation evidence. title: Cited crawled: anyOf: - type: integer - type: 'null' description: >- Served training and AI-search requests in window, verified true or unknown. Plugin counts are a floor. Null when this page is unmeasured. title: Crawled crawler_bots: anyOf: - items: $ref: '#/components/schemas/PageCrawlerBot' type: array - type: 'null' description: >- Per-bot served requests in window, verified true or unknown, including search engines. Categories come from the frozen measurement. Null when this page is unmeasured; empty when no requests qualify. title: Crawler Bots fetched_live: anyOf: - type: integer - type: 'null' description: >- Served user-fetch requests in window, verified true or unknown. Plugin counts are a floor. Null when this page is unmeasured. title: Fetched Live not_found: anyOf: - type: integer - type: 'null' description: >- Not-found requests from AI categories in window, across all verification states. Plugin counts are a floor. Null when unmeasured. title: Not Found search_clicks: anyOf: - type: integer - type: 'null' description: >- Search Console clicks in window. Null without a complete read of the current property returning this page for that window. title: Search Clicks search_engine_crawls: anyOf: - type: integer - type: 'null' description: >- Served search-engine requests in window, verified true or unknown. Plugin counts are a floor. Null when this page is unmeasured. title: Search Engine Crawls search_impressions: anyOf: - type: integer - type: 'null' description: >- Search Console impressions in window. Null without a complete read of the current property returning this page for that window. title: Search Impressions sources: anyOf: - items: type: string type: array - type: 'null' description: >- Crawler sources recorded for window. Null without a crawler measurement. title: Sources unverified: anyOf: - type: integer - type: 'null' description: >- Known-unverified requests from AI categories in window, across all outcomes. Unknown verification does not count here. Plugin counts are a floor. Null when unmeasured. title: Unverified window: anyOf: - $ref: '#/components/schemas/PageFunnelWindow' - type: 'null' description: >- 28 whole days ending two days before the newest pinned weekly scan started. Independent of period and figure filters. Null without a weekly scan. required: - window - sources - crawler_bots - search_clicks - search_impressions - crawled - fetched_live - cited - ai_visits - blocked - not_found - unverified - search_engine_crawls title: PageFunnel type: object V1PageRubric: properties: priority: description: >- The rubric's finding: ineligible, answer_gap and substance_gap are gaps. enum: - ineligible - unmeasured - answer_gap - substance_gap - ready title: Priority type: string score: description: >- Value times gap as the newest scan with page records scored the page; zero without a gap. Higher is a better fix. title: Score type: number required: - priority - score title: V1PageRubric type: object PageCrawlerBot: description: One bot's served requests for one page over the recorded crawler window. properties: bot: title: Bot type: string category: anyOf: - enum: - training - ai_search - user_fetch - search_engine type: string - type: 'null' title: Category hits: title: Hits type: integer operator: anyOf: - type: string - type: 'null' title: Operator required: - bot - operator - category - hits title: PageCrawlerBot type: object PageFunnelWindow: properties: clamped: description: >- True when the weekly scan this window belongs to completed before that history began. Crawler, visit and search measurements are then null. title: Clamped type: boolean end: description: Last day of the funnel window, inclusive. format: date title: End type: string history_days: description: >- Days back from today that the plan reads crawler, visit and search measurements. title: History Days type: integer start: description: First day of the funnel window, inclusive. format: date title: Start type: string required: - start - end - history_days - clamped title: PageFunnelWindow type: object securitySchemes: apiKey: description: 'An API key, sent as `Authorization: Bearer hrld_...`.' scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.