> ## 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 Audit > The latest crawl's readiness, site checks by group and pages. Audit has no period. Page citations count the last weekly scan, named in citations_scan. AI crawls use the same frozen 28-day window as page reads, ending two days before that weekly scan started. ## OpenAPI ````yaml /api-reference/openapi.json get /v1/brands/{brand_id}/audit 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}/audit: get: tags: - v1 summary: Get Audit description: >- The latest crawl's readiness, site checks by group and pages. Audit has no period. Page citations count the last weekly scan, named in citations_scan. AI crawls use the same frozen 28-day window as page reads, ending two days before that weekly scan started. operationId: getAudit parameters: - in: path name: brand_id required: true schema: format: uuid title: Brand Id type: string - 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: status required: false schema: anyOf: - enum: - readable - blocked_robots - noindex - does_not_load - needs_javascript - not_read type: string - type: 'null' title: Status - in: query name: cited required: false schema: anyOf: - enum: - cited - not_cited type: string - type: 'null' title: Cited - in: query name: page_type required: false schema: anyOf: - enum: - product - solution - pricing - blog_post - customer_story - press - documentation - resource - comparison - legal - other type: string - type: 'null' title: Page Type - in: query name: q required: false schema: anyOf: - maxLength: 200 type: string - type: 'null' title: Q - in: query name: sort required: false schema: default: citations enum: - citations - page - status - crawls - read title: Sort type: string - in: query name: direction required: false schema: anyOf: - enum: - asc - desc type: string - type: 'null' title: Direction - in: query name: check required: false schema: anyOf: - maxLength: 200 type: string - type: 'null' title: Check - in: query name: checks_limit required: false schema: default: 10 maximum: 100 minimum: 1 title: Checks Limit type: integer - in: query name: checks_offset required: false schema: default: 0 minimum: 0 title: Checks Offset type: integer responses: '200': content: application/json: schema: $ref: '#/components/schemas/V1Audit' 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: V1Audit: description: The latest crawl's site checks and pages. Audit has no period. properties: checks_failing: title: Checks Failing type: integer checks_unmeasured: title: Checks Unmeasured type: integer citations_scan: anyOf: - $ref: '#/components/schemas/DataAsOf' - type: 'null' description: The last weekly scan, whose answers the pages' citations count. crawled_at: anyOf: - format: date-time type: string - type: 'null' title: Crawled At crawler_hits_available: title: Crawler Hits Available type: boolean crawler_hits_days: title: Crawler Hits Days type: integer groups: items: $ref: '#/components/schemas/V1AuditGroup' title: Groups type: array limit: title: Limit type: integer meta: $ref: '#/components/schemas/Meta' description: Normalized query and newest included scan. next_crawl_at: anyOf: - format: date-time type: string - type: 'null' title: Next Crawl At 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 page_types: items: type: string title: Page Types type: array pages: items: $ref: '#/components/schemas/V1AuditPage' title: Pages type: array readiness: anyOf: - $ref: '#/components/schemas/V1Readiness' - type: 'null' sentence: anyOf: - type: string - type: 'null' title: Sentence state: enum: - ready - awaiting_first_crawl title: State type: string total: title: Total type: integer required: - meta - next_cursor - total - limit - offset - state - sentence - page_types - crawler_hits_available - crawled_at - next_crawl_at - readiness - checks_failing - checks_unmeasured - groups - crawler_hits_days - citations_scan - pages title: V1Audit 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 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 V1AuditGroup: properties: checks: items: $ref: '#/components/schemas/V1AuditCheck' title: Checks type: array failing: title: Failing type: integer name: title: Name type: string passing: title: Passing type: integer unmeasured: title: Unmeasured type: integer required: - name - failing - passing - unmeasured - checks title: V1AuditGroup 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 V1AuditPage: properties: citations: anyOf: - type: integer - type: 'null' description: >- Citations in the last weekly scan, citations_scan; null where that scan could not keep all its citations. title: Citations crawler_hits: anyOf: - type: integer - type: 'null' description: >- Served crawler requests from the same frozen 28-day weekly scan window as page reads, ending two days before the scan started. title: Crawler Hits funnel: anyOf: - $ref: '#/components/schemas/PageFunnel' - type: 'null' description: The page funnel on the pinned weekly window; null without a page id. gates: items: $ref: '#/components/schemas/V1AuditGate' title: Gates type: array page_id: anyOf: - format: uuid type: string - type: 'null' title: Page Id page_type: title: Page Type type: string path: title: Path type: string read_at: anyOf: - format: date-time type: string - type: 'null' title: Read At status: enum: - readable - blocked_robots - noindex - does_not_load - needs_javascript - not_read title: Status type: string status_word: title: Status Word type: string title: anyOf: - type: string - type: 'null' title: Title url: title: Url type: string required: - funnel - path - status_word - url - title - page_id - page_type - status - gates - citations - crawler_hits - read_at title: V1AuditPage type: object V1Readiness: description: >- The pages the readiness checks cover: every audited page and the homepage. properties: pages_blocked: title: Pages Blocked type: integer pages_checked: title: Pages Checked type: integer pages_readable: title: Pages Readable type: integer pages_unmeasured: title: Pages Unmeasured type: integer required: - pages_checked - pages_readable - pages_blocked - pages_unmeasured title: V1Readiness 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 V1AuditCheck: properties: action_id: anyOf: - format: uuid type: string - type: 'null' title: Action Id failing_pages: description: >- Up to checks_limit pages the check fails, starting at failing_pages_offset. items: type: string title: Failing Pages type: array failing_pages_offset: default: 0 title: Failing Pages Offset type: integer failing_pages_total: title: Failing Pages Total type: integer id: title: Id type: string label: title: Label type: string measured: anyOf: - type: string - type: 'null' title: Measured met: anyOf: - type: boolean - type: 'null' description: Null where the scan could not measure it. title: Met pages_in_scope: title: Pages In Scope type: integer target: title: Target type: string required: - id - label - target - measured - met - failing_pages - failing_pages_total - action_id - failing_pages_offset - pages_in_scope title: V1AuditCheck type: object JsonValue: {} 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 V1AuditGate: properties: key: title: Key type: string status: enum: - pass - fail - unmeasured title: Status type: string required: - key - status title: V1AuditGate 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.