> ## 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.

# Start Snapshot

> Start a Snapshot of a domain as the key's member, in its organization, and draft
its profile: brand, description and market. Waits up to 15 seconds for the profile;
a null `profile` is still drafting, and getScan reads it later. Nothing is spent
until runSnapshot. A domain whose Snapshot of yours has not run answers that
Snapshot with 200. Needs a full-access key.



## OpenAPI

````yaml /api-reference/openapi.json post /v1/scans
openapi: 3.1.0
info:
  description: >-
    Access to one organization's brands, as the member who created the API key.
    A read-only key reads; a full-access key also starts, edits and runs that
    member's Snapshots on the organization's Snapshot credits. Each key may make
    120 requests a minute. Separate organization service tokens can start
    Snapshots and Full audits and read service audits. Every error is an RFC
    9457 problem (`application/problem+json`) whose `code` names it.
  summary: Read your brands' AI visibility and run Snapshots in Heralded.
  title: Heralded API
  version: '1'
servers:
  - url: https://api.heralded.ai
security: []
paths:
  /v1/scans:
    post:
      tags:
        - v1
      summary: Start Snapshot
      description: >-
        Start a Snapshot of a domain as the key's member, in its organization,
        and draft

        its profile: brand, description and market. Waits up to 15 seconds for
        the profile;

        a null `profile` is still drafting, and getScan reads it later. Nothing
        is spent

        until runSnapshot. A domain whose Snapshot of yours has not run answers
        that

        Snapshot with 200. Needs a full-access key.
      operationId: startSnapshot
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SnapshotStart'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V1StartedSnapshot'
          description: Your Snapshot of this domain that has not run yet.
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V1StartedSnapshot'
          description: Successful Response
        '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: https://docs.heralded.ai/errors-and-limits#invalid_token
              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
        '402':
          content:
            application/problem+json:
              example:
                code: no_credits
                detail: No free Snapshot or Snapshot credit can pay for this Snapshot.
                instance: example-request-id
                resets_at: '2026-12-08T09:30:00+00:00'
                status: 402
                title: Payment Required
                type: https://docs.heralded.ai/errors-and-limits#no_credits
              schema:
                $ref: '#/components/schemas/Problem'
          description: >-
            Nothing can pay: no free Snapshot and no Snapshot credit
            (`no_credits`), or every credit is held by your unrun Snapshots
            (`credits_held`). `resets_at` says when a free Snapshot opens again,
            where one will.
        '403':
          content:
            application/problem+json:
              example:
                code: insufficient_scope
                detail: >-
                  The credential does not have the scope this operation
                  requires.
                instance: example-request-id
                status: 403
                title: Forbidden
                type: https://docs.heralded.ai/errors-and-limits#insufficient_scope
              schema:
                $ref: '#/components/schemas/Problem'
          description: >-
            A read-only key or the web's session (`insufficient_scope`, with the
            scope challenge), or a member whose role cannot run Snapshots in the
            key's organization (`forbidden`).
          headers:
            WWW-Authenticate:
              description: The scope challenge on `insufficient_scope`.
              schema:
                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: https://docs.heralded.ai/errors-and-limits#not_found
              schema:
                $ref: '#/components/schemas/Problem'
          description: No resource this caller can read.
        '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: https://docs.heralded.ai/errors-and-limits#workspace_archived
              schema:
                $ref: '#/components/schemas/Problem'
          description: The API key's organization is archived.
        '422':
          content:
            application/problem+json:
              example:
                code: invalid_domain
                detail: >-
                  The domain is not a website Heralded can read. Check its
                  spelling.
                instance: example-request-id
                status: 422
                title: Unprocessable Content
                type: https://docs.heralded.ai/errors-and-limits#invalid_domain
              schema:
                $ref: '#/components/schemas/Problem'
          description: >-
            The domain is no website Heralded can read (`invalid_domain`), a
            platform's address (`platform_domain`), or the body is invalid
            (`invalid_request`).
        '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: https://docs.heralded.ai/errors-and-limits#rate_limited
              schema:
                $ref: '#/components/schemas/RateLimitProblem'
          description: >-
            The key made more than 120 requests in the minute (`rate_limited`),
            or today's free Snapshots are all taken (`free_snapshots_exhausted`,
            with `resets_at`).
          headers:
            Retry-After:
              description: Seconds until the key may call again.
              schema:
                example: 60
                type: integer
        '503':
          content:
            application/problem+json:
              example:
                code: scans_temporarily_paused
                detail: Heralded has paused new scan starts. Retry later.
                instance: example-request-id
                status: 503
                title: Service Unavailable
                type: >-
                  https://docs.heralded.ai/errors-and-limits#scans_temporarily_paused
              schema:
                $ref: '#/components/schemas/Problem'
          description: New scan starts are paused.
      security:
        - apiKey: []
components:
  schemas:
    SnapshotStart:
      additionalProperties: false
      properties:
        domain:
          description: The website to measure, such as acme.com.
          maxLength: 253
          minLength: 1
          title: Domain
          type: string
      required:
        - domain
      title: SnapshotStart
      type: object
    V1StartedSnapshot:
      properties:
        audit_progress:
          anyOf:
            - $ref: '#/components/schemas/AuditProgress'
            - type: 'null'
          description: An Audit's live page and screenshot counts; null on other scans.
        brand_id:
          anyOf:
            - format: uuid
              type: string
            - type: 'null'
          description: Null for a Snapshot no brand holds.
          title: Brand Id
        completed_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: When it completed, failed or expired; null until then.
          title: Completed At
        created:
          description: >-
            False when the start returned your Snapshot of this domain that has
            not run yet.
          title: Created
          type: boolean
        domain:
          description: The site the scan measured.
          title: Domain
          type: string
        ecommerce:
          description: >-
            Whether the scan measured the brand as ecommerce, which reads
            product cards and Google Shopping. Fixed for the scan once it runs.
          title: Ecommerce
          type: boolean
        failure_reason:
          anyOf:
            - type: string
              x-extensible-enum:
                - stuck_no_progress
                - brief_abandoned
                - insufficient_engine_signal
                - cost_cap_exceeded
                - report_inputs_missing
                - service_unavailable
                - other
            - type: 'null'
          description: >-
            Why the scan failed, one of `stuck_no_progress`, `brief_abandoned`,
            `insufficient_engine_signal`, `cost_cap_exceeded`,
            `report_inputs_missing`, `service_unavailable` or `other`; null
            unless the scan failed. New values may be added.
          title: Failure Reason
        id:
          description: The scan's id.
          format: uuid
          title: Id
          type: string
        issued:
          anyOf:
            - $ref: '#/components/schemas/V1ScanFacts'
            - type: 'null'
          description: >-
            What the scan issued once complete; null while it runs, while it is
            partial, on a daily scan and on an Audit.
        kind:
          description: >-
            `weekly`, `daily`, `snapshot` (a one-time Snapshot or a brand's
            first) or `audit`.
          enum:
            - weekly
            - daily
            - snapshot
            - audit
          title: Kind
          type: string
        meta:
          $ref: '#/components/schemas/Meta'
          description: Normalized query and newest included scan.
        partial:
          description: >-
            A Snapshot delivered before every answer came back, still filling
            in.
          title: Partial
          type: boolean
        payer:
          anyOf:
            - $ref: '#/components/schemas/V1SnapshotPayer'
            - type: 'null'
          description: >-
            Who pays for a Snapshot: recorded on Run, charged when it starts. A
            run that needs action keeps the payer it waits on. Null before Run,
            after a stop and on other scans.
        profile:
          anyOf:
            - $ref: '#/components/schemas/V1SnapshotProfile'
            - type: 'null'
          description: >-
            A preparing Snapshot's profile, to confirm or edit before Run; null
            while it drafts and once the Snapshot runs.
        progress:
          anyOf:
            - $ref: '#/components/schemas/V1ScanProgress'
            - type: 'null'
          description: Null on an Audit and once the scan completed or failed.
        questions_asked:
          anyOf:
            - type: integer
            - type: 'null'
          description: >-
            How many questions the scan asks AI engines. A Snapshot asks 20, or
            12 to 19 when fewer of its drafted questions passed review. Null
            before its questions are fixed and on an Audit.
          title: Questions Asked
        report_url:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            A delivered Snapshot's or weekly scan's report page, to give the
            member; null on an Audit, a daily scan and before delivery.
          title: Report Url
        run_request:
          anyOf:
            - $ref: '#/components/schemas/V1RunRequest'
            - type: 'null'
          description: Run pressed before the Snapshot started; null otherwise.
        sells_to:
          description: >-
            Who the scan measured the brand as selling to: `businesses` or
            `consumers`. Fixed for the scan once it runs.
          enum:
            - businesses
            - consumers
          title: Sells To
          type: string
        share_id:
          anyOf:
            - format: uuid
              type: string
            - type: 'null'
          description: >-
            The report link id once delivered; null on a daily scan and before
            delivery. Quick shares use /v1/shared/audits/{share_id}; Base and
            Full remain owner-only.
          title: Share Id
        started_at:
          description: When the scan was started.
          format: date-time
          title: Started At
          type: string
        state:
          description: >-
            `preparing` while the profile drafts or waits for Run, `running`,
            `completed`, `failed`, or `expired`: a Snapshot whose profile waited
            24 hours without a run.
          enum:
            - preparing
            - running
            - completed
            - failed
            - expired
          title: State
          type: string
        url:
          description: >-
            The Snapshot's page, where its member can check the profile, run it
            and follow it.
          title: Url
          type: string
      required:
        - meta
        - id
        - kind
        - state
        - partial
        - brand_id
        - domain
        - sells_to
        - ecommerce
        - started_at
        - completed_at
        - questions_asked
        - profile
        - run_request
        - payer
        - share_id
        - report_url
        - progress
        - audit_progress
        - failure_reason
        - issued
        - url
        - created
      title: V1StartedSnapshot
      type: object
    Problem:
      description: An RFC 9457 problem linking its code to human-readable documentation.
      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:
          title: Type
          type: string
      required:
        - type
        - title
        - status
        - detail
        - code
        - instance
      title: Problem
      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:
          title: Type
          type: string
      required:
        - type
        - title
        - status
        - detail
        - code
        - instance
        - rate_limit
      title: RateLimitProblem
      type: object
    AuditProgress:
      properties:
        found:
          title: Found
          type: integer
        phase:
          enum:
            - discovering
            - reading
            - judging
            - done
            - failed
          title: Phase
          type: string
        planned:
          title: Planned
          type: integer
        read:
          title: Read
          type: integer
        shots:
          title: Shots
          type: integer
      required:
        - phase
        - found
        - read
        - planned
        - shots
      title: AuditProgress
      type: object
    V1ScanFacts:
      properties:
        heralded_score:
          anyOf:
            - $ref: '#/components/schemas/V1IssuedScore'
            - type: 'null'
          description: The Heralded Score this Snapshot issued.
        mentioned:
          anyOf:
            - $ref: '#/components/schemas/V1IssuedRate'
            - type: 'null'
          description: Mentioned, ranked among this Snapshot's rivals.
        missing_question:
          anyOf:
            - $ref: '#/components/schemas/RivalQuestion'
            - type: 'null'
          description: >-
            The unbranded question the strongest scored competitor was named for
            most often while you went unnamed. Null when it won none. Tied
            competitors follow name order; tied questions follow the order
            asked.
        readiness:
          anyOf:
            - $ref: '#/components/schemas/V1Readiness'
            - type: 'null'
          description: >-
            AI engines' access to the pages this scan checked; null where it
            checked none.
        recommended:
          anyOf:
            - $ref: '#/components/schemas/V1IssuedRate'
            - type: 'null'
          description: Recommended, ranked among this Snapshot's rivals.
      required:
        - heralded_score
        - mentioned
        - recommended
        - missing_question
        - readiness
      title: V1ScanFacts
      type: object
    Meta:
      properties:
        data_as_of:
          anyOf:
            - $ref: '#/components/schemas/DataAsOf'
            - type: 'null'
        last_attempt_failed:
          default: false
          description: The newest attempt failed; the last good result is displayed.
          title: Last Attempt Failed
          type: boolean
        partial:
          default: false
          description: The displayed response includes a partial report.
          title: Partial
          type: boolean
        query:
          additionalProperties:
            $ref: '#/components/schemas/JsonValue'
          title: Query
          type: object
        surfaces:
          additionalProperties:
            $ref: '#/components/schemas/SurfaceFreshness'
          description: >-
            Freshness by Command Center surface key. Each entry describes its
            own displayed result, including results without a scan.
          title: Surfaces
          type: object
        updating:
          default: false
          description: A newer result is being produced or is not yet displayed.
          title: Updating
          type: boolean
      required:
        - query
        - data_as_of
        - partial
        - updating
        - last_attempt_failed
        - surfaces
      title: Meta
      type: object
    V1SnapshotPayer:
      properties:
        by:
          description: >-
            `free_snapshot`: the member's free Snapshot. `credits`: the
            organization's Snapshot credits.
          enum:
            - free_snapshot
            - credits
          title: By
          type: string
        organization_id:
          anyOf:
            - format: uuid
              type: string
            - type: 'null'
          description: The organization whose credits pay; null for a free Snapshot.
          title: Organization Id
      required:
        - by
        - organization_id
      title: V1SnapshotPayer
      type: object
    V1SnapshotProfile:
      description: The profile a Snapshot measures, which its member confirms before Run.
      properties:
        brand_name:
          description: The brand the Snapshot measures.
          title: Brand Name
          type: string
        buyer:
          anyOf:
            - type: string
            - type: 'null'
          description: Who buys from the brand, from the drafted target buyer.
          title: Buyer
        category:
          anyOf:
            - type: string
            - type: 'null'
          description: The market category drafted for the brand.
          title: Category
        competitors:
          description: >-
            Competitor names drafted for the Snapshot so far. Read-only: a
            Snapshot ranks the competitors its AI answers name. Empty while they
            are still drafting.
          items:
            type: string
          title: Competitors
          type: array
        description:
          anyOf:
            - type: string
            - type: 'null'
          description: What the brand does, in a sentence.
          title: Description
        market:
          description: >-
            Where AI engines are asked: `global`, `europe` or a country code
            such as `US`.
          title: Market
          type: string
      required:
        - brand_name
        - description
        - category
        - buyer
        - competitors
        - market
      title: V1SnapshotProfile
      type: object
    V1ScanProgress:
      properties:
        answers_read:
          description: Answers that came back so far, failed ones included.
          title: Answers Read
          type: integer
        answers_total:
          description: Answers planned for this scan.
          title: Answers Total
          type: integer
        pages_checked:
          anyOf:
            - type: integer
            - type: 'null'
          description: Cited pages read so far; null before then.
          title: Pages Checked
        pages_total:
          anyOf:
            - type: integer
            - type: 'null'
          description: >-
            Cited page URLs scheduled for verification in this scan; null before
            then.
          title: Pages Total
        pct:
          title: Pct
          type: integer
        phase:
          description: The step the scan is on, such as engines or scoring.
          title: Phase
          type: string
      required:
        - phase
        - pct
        - answers_read
        - answers_total
        - pages_checked
        - pages_total
      title: V1ScanProgress
      type: object
    V1RunRequest:
      description: Run pressed on a Snapshot that has not started.
      properties:
        reason:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            Why a `needs_action` run did not start, as an error code such as
            `no_credits`; null otherwise.
          title: Reason
        state:
          description: >-
            `requested`: the run starts once the profile is drafted. `stopped`:
            an edit or Stop cancelled it; Run again to start it. `needs_action`:
            it could not start, for `reason`.
          enum:
            - requested
            - stopped
            - needs_action
          title: State
          type: string
      required:
        - state
        - reason
      title: V1RunRequest
      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
    V1IssuedScore:
      properties:
        answers:
          title: Answers
          type: integer
        band:
          title: Band
          type: string
        high:
          title: High
          type: integer
        low:
          title: Low
          type: integer
        value:
          title: Value
          type: integer
      required:
        - value
        - low
        - high
        - band
        - answers
      title: V1IssuedScore
      type: object
    V1IssuedRate:
      properties:
        high:
          title: High
          type: integer
        k:
          description: The answers that counted.
          title: K
          type: integer
        low:
          title: Low
          type: integer
        'n':
          description: The answers read.
          title: 'N'
          type: integer
        rank:
          anyOf:
            - type: integer
            - type: 'null'
          description: >-
            The brand's place among the rivals this scan scored; null where no
            answer counted the brand.
          title: Rank
        rank_of:
          description: The brand and every rival measured.
          title: Rank Of
          type: integer
        value:
          title: Value
          type: integer
      required:
        - value
        - low
        - high
        - k
        - 'n'
        - rank
        - rank_of
      title: V1IssuedRate
      type: object
    RivalQuestion:
      properties:
        answers:
          description: Answers that named this competitor while leaving you unnamed.
          title: Answers
          type: integer
        competitor:
          title: Competitor
          type: string
        query_id:
          format: uuid
          title: Query Id
          type: string
        question:
          title: Question
          type: string
      required:
        - query_id
        - question
        - competitor
        - answers
      title: RivalQuestion
      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
    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: {}
    SurfaceFreshness:
      properties:
        as_of:
          anyOf:
            - $ref: '#/components/schemas/SurfaceAsOf'
            - type: 'null'
          description: The result displayed here.
        last_attempt_failed:
          default: false
          description: The newest attempt failed; any displayed result is retained.
          title: Last Attempt Failed
          type: boolean
        partial:
          default: false
          description: The displayed report is partial.
          title: Partial
          type: boolean
        updating:
          default: false
          description: A newer attempt exists whose result is not yet displayed.
          title: Updating
          type: boolean
      required:
        - as_of
        - partial
        - updating
        - last_attempt_failed
      title: SurfaceFreshness
      type: object
    SurfaceAsOf:
      properties:
        at:
          description: When the displayed result was measured.
          format: date-time
          title: At
          type: string
        scan_id:
          anyOf:
            - format: uuid
              type: string
            - type: 'null'
          description: The result's scan, null for a timestamp-only result.
          title: Scan Id
      required:
        - scan_id
        - at
      title: SurfaceAsOf
      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.