> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getclean.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> getclean's own MCP server is at https://mcp.getclean.ai/mcp. The /mcp path of this docs site is Mintlify's search over these pages, not getclean.
> Every answer of the API opens with outcome. A page that could not be read is a record whose outcome says why, never an HTTP error; read outcome before anything else.
> The API's contract is the OpenAPI 3.1 file at https://docs.getclean.ai/openapi.yaml; the SDKs are generated from it.
> The product's name is written getclean, in lower case.

# Get search

> Read a search you already have, free: the first page as it was answered, and behind it the full list the search stored, including the results it dropped and why. Nothing is searched again and nothing is charged; only the record's `expires_at` moves.

The first page is the original answer as stored, whatever `page_size`: its members and the notices kept with it. A notice of the original answer that was not kept does not come back, and `dropped_reason` is absent on every candidate. A later page is the stored list in rank order, and every item on it carries `dropped_reason`. Every other member comes as stored; `request_id` is this call's, and `expires_at` is the record's new one. `next_page_token` comes while more remain. `fetch_contents` reads a candidate by its URL.

## What it costs

The key needs `search:read`. The call is free. The answer is `200` with `Search`; the call moves the record's `expires_at` 48 hours ahead.

## Refused before any work

A value outside its set or range, `page_size` above its maximum excepted, which is lowered with the notice `page_size_lowered`: `400 invalid-request`, `not_allowed` or `bound`, each with where it is. An id of the wrong kind: `400 invalid-request`, before any lookup. A token of another search or another query: `400 page-token-invalid`. An unknown query parameter: `400 invalid-request`, `unknown_field`.

## Notices this operation makes

The search's own notices first, then `page_size_lowered` and `version_retiring`.

## Problem types

* 400 `invalid-request`, The request is invalid; `page-token-invalid`, The page token is invalid.
* 401 `unauthorized`, The key is missing or rejected.
* 403 `insufficient-scope`, The key lacks a scope this call needs.
* 404 `not-found`, Not found: an unknown or another account's search.
* 410 `search-expired`, The search has expired: for 30 days after it expired, to the owning account only, with `expired_at` and `change` naming `search`; then `404`.
* 429 `rate-limit-exceeded`, The rate limit is exceeded; `concurrency-limit-exceeded`, Too many calls are in flight.
* 500 `internal-error`, The service failed.
* 503 `overloaded`, The service is overloaded.


## OpenAPI

````yaml /openapi.yaml get /v1/search/{search_id}
openapi: 3.1.0
info:
  title: getclean API
  version: 1.0.0
  description: >-
    getclean is the data layer for research agents. Every call is shaped around
    one step of research, and every answer is made to be reasoned from and
    cited. Give it a URL, a file or a question. What comes back answers the
    questions a researcher has of a source. What it says, exactly: the main
    content with every heading, table, merged cell, strikethrough and word as
    the source carries them, the same on every read. Where it says it: section
    and block ids that hold across every read, and the places where your own
    words or questions stand. As of when: the dates the source declares, and on
    request the page as an archive held it on a past day. Whether to trust it:
    what the page hides, what was left out, who publishes it, and what it
    declares about its use. What changed since you last looked: a fingerprint,
    and a comparison block by block and cell by cell. What it cost: a ceiling
    you set before, and the bill after.


    Every record is kept, so every later question about the same source is
    answered from the same copy, free. No model judges the content unless you
    ask for it: the summary, the schema fill and the judged highlights are steps
    you name, each listed in the answer with its version, and
    `deterministic_only` turns every judging step off. Two steps run on their
    own and are listed too: text recognition on a scanned page, a fixed step
    that repeats under one version, and the identification of a publisher
    getclean has not seen before, which costs you nothing. A search runs two
    model steps by default, the ranking of its results and the choice of
    sources; the same switch turns them off.


    There are two groups of calls, called families here. The contents family
    takes one source, a web page or a document, by URL or as a file, and makes
    its record: the content in the formats you ask for, the map of its sections,
    its blocks and links, the places where it says a thing, the facts of the
    source, a fingerprint and the price. The search family runs one question, in
    up to twenty wordings, on up to ten datasources at once, merges the results
    into one ranked list, and returns them with their facts and a receipt of
    what ran where, before any page is read. Every answer of either is a record
    with an id, `cnt_` for a source and `srch_` for a search, that every later
    call names.


    Every record opens with `outcome`: what happened at the source, never an
    HTTP status. A page that could not be read is still a record, whose outcome
    says why and what may work next, and the bill follows the outcome: a read
    that failed, was refused or needs a person costs nothing. Only a request
    getclean itself refuses, a bad field, a missing credential, a cap too low,
    is an HTTP error, with a problem body that says whose move it is.


    ## The words this contract uses


    - A record is one result of one billed call. It is kept 48 hours after its
    last call and at most 30 days from its making; `expires_at` names the
    moment, and every call on the record moves it forward within that cap. After
    that, a call on the record is `410` for 30 days, then `404`.

    - A page is a web page at a URL. A document is a file, read at a URL or
    uploaded; a document page is one page of such a file; a page of results is
    one page of a list. Page alone means a web page.

    - A character is one Unicode code point. Every text limit, `max_characters`
    among them, counts characters so.

    - A closed set lists every value a member will ever take. An open set lists
    the values served now, and a later version may add one, so read an unknown
    value as a new one, never as an error.

    - The key is whichever credential you sent, an API key or an access token. A
    field that depends on the key, such as the cap on one call, reads the
    account that credential stands for.

    - The smallest call is a call with nothing extra: one `contents` unit for a
    fetch, one `searches` and one `datasource_queries` unit for a search. A cap
    below it is refused before any work.

    - A run groups records under one budget. Every key has one run,
    `run_default`, and this contract names no other.

    - The kind of source, `carrier`, is `web` for a live page, `archive` for an
    archive's copy of a page read under `as_of_date`, and `upload` for bytes you
    sent.

    - A view of a page is `main`, the main content alone, or `whole_page`,
    everything on the page; the field is `scope`. A document has one view.


    ## The credential


    Every call carries `Authorization: Bearer <key>`. The bearer value is an API
    key from `https://app.getclean.ai` or an access token issued by
    `https://auth.getclean.ai/realms/getclean`. Either resolves to one account
    with its scopes, its cap on one call, its budgets, its policy and its
    default run. A credential in the query string is ignored. A call with no
    usable credential is answered `401` with `WWW-Authenticate: Bearer
    realm="getclean",
    resource_metadata="https://api.getclean.ai/.well-known/oauth-protected-resource"`.
    That address serves the API's protected resource metadata (RFC 9728) to
    anyone, outside the versioned paths, with `Cache-Control: max-age=3600`:
    `resource` `https://api.getclean.ai`, `authorization_servers` the one
    issuer, `scopes_supported` the nine scopes, `bearer_methods_supported`
    `["header"]`. It is not an operation of this contract. An agent that arrives
    with nothing follows it to the issuer and its device sign-in.


    ## HEAD, 405 and 406


    Every `GET` of both families answers `HEAD` at once with the headers the
    `GET` would send and no body; a `HEAD` on `get_job` does not wait. The
    contract declares no `HEAD` operations. A method the resource does not offer
    is answered `405` with `Allow`; a representation it cannot give, `406`; each
    a problem of type `about:blank` whose title is the status's reason phrase.
    The contract declares neither per operation.


    ## What every answer promises, and what it does not


    - The reason `whole` means that everything you asked for fit. It does not
    promise that what came is the article: a page that is not what its address
    promises can come back as content, an error page sent with status 200, a
    subscription offer, a page with no main content, a portal that shows its
    results only inside a session. `not_found` comes from the status code alone.

    - A challenge, a block, a sign-in page or a purchase wall is recognized by
    signs in the response or on the page, never by its words. Such a sign
    decides before the status code. A wall with no known sign comes back as
    content. A page that declares its content not free carries the notice
    `paywall_declared`, whatever came.

    - The main content is what getclean keeps as the page's substance. It can
    leave real content out as another part; `left_out` names the kinds and sizes
    left out, and `get_contents` with `scope: whole_page` shows the rest, free.
    When no main content is found but the page has text or links, the whole page
    is delivered under `scope: whole_page` with the notice `no_main_content`.

    - Some regions of a page cannot be read as text. Where such a region covers
    part of the main content, the notice `unread_region` names its kind and
    size. A feed that grows as it is scrolled is read to a limit, never to its
    end. A frame from another site is an `embed` block with its address.

    - A page is read for at most `wait_seconds` and measured as it stands at
    that moment. A page still changing then carries the notice `not_settled`.
    The reason `deadline` means only that nothing readable had come by then.

    - Text that a reader of the page cannot see is kept apart in `hidden_text`,
    with the reason, never mixed into the content. Text hidden in a way getclean
    does not detect comes back as content. Hidden text is looked for in web
    pages and HTML files only. Keeping it apart is the default, since nothing is
    lost.

    - `title`, `authors`, `published_date`, `published_at`, `modified_date`,
    `publisher`, `canonical_url`, `language`, `language_versions`,
    `structured_data` and `declared_terms` are what the page or the document
    declares about itself; getclean does not check them against the content. A
    document's own dates often record when the file was made.

    - On a page whose headings are styled text rather than heading markup, the
    heading levels follow the styling and may nest wrongly.

    - The default sizes, `max_characters` 20,000 among them, were chosen with
    Latin script in mind. A text in a denser script, Chinese or Japanese, holds
    more in the same count, and no default is set per script.

    - A price that reads 0 may not be the price the page shows; check `counts`
    and the page's kind before trusting it.

    - The fingerprint compares only within one `scope`, one `execution.version`,
    one `execution.configuration` and one kind of source. A different
    fingerprint means the kept text differs, not that the article changed, since
    a site can serve two visits two different pages. `compare_contents` shows
    where.

    - On a web page, `unchanged` still reads the page in full and bills the
    fetch; what it saves is the text not sent and your agent's time, never the
    price. On a document whose bytes match the fingerprint's record, no page is
    parsed or billed.

    - Under one `execution.version` and `execution.configuration`, the same page
    or the same bytes give the same content and the same `s` and `b` ids on
    every call. A model step names its version and is not promised to repeat;
    `exact` and `near` matches repeat.

    - `challenge_served` may repeat on sites that challenge every new visitor.

    - Text inside images is not recognized on a page or a document that has a
    text layer; your agent reads it from `image.url`.

    - A link's kind is taken from its address, a guess; no request is made per
    link, so a link carries no size or served type.

    - An archive copy is the page as the archive served it, its links pointing
    into the archive. `fetched_at` is when getclean read the copy. `robots` is
    the site's own robots file as read now.

    - `page_number` is the page's position in the file, counted from 1;
    `page_label` is the label the document itself prints on the page, where it
    declares one.

    - A page that redirects elsewhere is delivered as what arrived; `final_url`
    and `redirects` show the path, and the notice `redirected` says when the
    final URL differs beyond the scheme, the host's case, a trailing slash and
    tracking parameters. Whether it is still the source is your agent's call.

    - `fetched_at` is getclean's own clock; no outside time source signs it.

    - A document's own arithmetic is not checked. Cells come as displayed,
    `formula_cells` says where a formula stood on a spreadsheet, and whether the
    figures satisfy the document's totals is your agent's check from the table's
    cells.

    - A highlight's place is a block id, a section id and the words as found,
    with a mark in the text returned, never an offset in characters, since the
    text is markdown whose offsets move with every mark and every format.

    - What this API does not do, and what it answers instead:
      - translate a page, or transcribe a recording; a recording's time ranges and frames: `unsupported_media_type`;
      - read a structure too large to take whole by its rows or a named column: `too_large`, with the count read;
      - sign in to a site for a fetch by URL: `sign_in_needed`; a registered login serves only a fetch made inside a search;
      - compose a text in force from its amendments, fill a template from several documents, or group copies: your agent's work, from each record's blocks and ids.
    - The price of a document is unknown before the call, since its page count
    is known only once it is downloaded. `max_cost` is the protection, and a
    fetch at the smallest call's price with `max_characters: 0` returns
    `pages.count` and the outline for one `contents` unit.

    - What your agent does from a record, with its blocks, ids and digests:
      - compare a clause with a clause of another document;
      - parse a displayed number, or a document's number format, which getclean does not declare;
      - judge whether a text was written by a machine, which getclean does not judge;
      - match two images, which getclean matches by identical bytes only; a web image's bytes are not kept;
      - read a reporter's page citation from an opinion's text.
    - A page exists only where the format has pages. A web page carries no page,
    and a page number printed in its text is your agent's to read.

    - An uploaded HTML file is read from its bytes alone, with nothing fetched
    and nothing run, so the styles, scripts and images it only points to are not
    loaded and its main content may differ from what the person saw; no
    screenshot is made.

    - A baseline you hold yourself is the whole text the record returned, since
    its hash is checked; a partial text cannot be compared.

    - What getclean did to a page is described by its published configuration at
    its version, with `left_out` and `hidden_text`; there is no log per read
    beyond them.

    - A markup change that keeps the text and its order is invisible to the
    comparison, since the record is the content.

    - A recognized page comes in the reading order the recognition produced,
    unmarked; headings come as text; pictures inside the page are not separated;
    a region the source blacked out is not told apart from a failed recognition.

    - An agent that checks a page again after its record expired gets
    `fingerprint_unknown` and pays the full price; it keeps the earlier text
    itself and compares with `compare_contents`.

    - A second-factor prompt counts as a sign-in page.

    - Content inside an app is not read; only pages and documents are.

    - The API has no field for a referrer or for a site's own settings; a
    setting reaches the read only through the URL.

    - A page's `declared_terms` are the page's; an image's licence is read on
    the image's own page.

    - getclean pays no site for a page. A page that asks a price ends
    `payment_required`, with the price in `cost.source_price`.
servers:
  - url: https://api.getclean.ai
security:
  - bearer: []
paths:
  /v1/search/{search_id}:
    get:
      summary: Get search
      description: >-
        Read a search you already have, free: the first page as it was answered,
        and behind it the full list the search stored, including the results it
        dropped and why. Nothing is searched again and nothing is charged; only
        the record's `expires_at` moves.
      operationId: get_search
      parameters:
        - $ref: '#/components/parameters/Traceparent'
        - name: search_id
          in: path
          required: true
          description: The search record, an `srch_` id as `search` returned it.
          schema:
            type: string
            pattern: ^srch_[A-Za-z0-9]{22}$
          example: srch_4HmUunqCCXquleKVCosqFG
        - name: view
          in: query
          required: false
          description: >-
            How much of the record comes back: `full`, every member, or
            `compact`, the smaller form the `Search` schema lists. Default
            `full`; the MCP server always asks for `compact`.
          schema:
            $ref: '#/components/schemas/View'
        - name: page_size
          in: query
          required: false
          description: >-
            Results per page of the stored list, from 1; the maximum, 50, stands
            in `Limits.bounds`, and a larger value is lowered with the notice
            `page_size_lowered`. Default the search's `max_candidates`.
          schema:
            type: integer
            minimum: 1
        - name: page_token
          in: query
          required: false
          description: >-
            The next page of the stored list, as the last answer's
            `next_page_token` gave it; opaque, at most 1,024 characters, alive
            as long as the record. Default none, the first page.
          schema:
            type: string
            minLength: 1
            maxLength: 1024
      responses:
        '200':
          description: >-
            The search record as stored: the first page as it was answered, or a
            later page of the stored list with `dropped_reason` on every item;
            `next_page_token` while more remain.
          headers:
            Request-Id:
              $ref: '#/components/headers/RequestId'
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimitPolicy'
            Sunset:
              $ref: '#/components/headers/Sunset'
            Deprecation:
              $ref: '#/components/headers/Deprecation'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Search'
              examples:
                get_search.delivered:
                  summary: >-
                    A later page of the stored list, a dropped candidate with
                    its reason, every other member as stored
                  value:
                    id: srch_4HmUunqCCXquleKVCosqFG
                    retention: hold
                    outcome:
                      kind: delivered
                      reason: candidates
                    notices: []
                    coverage_gaps: []
                    candidates:
                      - id: cand_b7v7hQoJ35NvgmndljizaO
                        url: https://example.org/commentary
                        title: Commentary
                        dropped_reason: not_relevant
                        relevance_score: 0.31
                        fetch_cost:
                          amount: '0.0050'
                          currency: USD
                        source_profile:
                          kind: press
                          role: secondary
                          independence: unknown
                          review:
                            kind: editorial
                            by: null
                        copy_count: 0
                        language_versions: []
                        carrier: web
                        access:
                          kind: open
                          declared_terms: []
                          robots: allowed
                        identifier_matches: []
                        excerpts: []
                        matches:
                          - wording_index: 0
                            datasource_id: web
                            rank: 17
                    counts:
                      returned: 3
                      found: 41
                      dropped:
                        not_relevant: 30
                        undated: 0
                        max_per_domain: 0
                        blocked_domain: 0
                        outside_allowed: 0
                        source_kind: 0
                        source_independence: 0
                        folded_copy: 8
                        phrase_check: 0
                        exclusion_check: 0
                        beyond_max_candidates: 0
                    end_reason: relevance
                    interpretation:
                      canonical_query: EU AI Act article 50 marking obligations
                      phrases: []
                      exclusions: []
                      operators: []
                      wordings:
                        - index: 0
                          text: EU AI Act article 50 marking obligations
                          language: en
                          language_basis: detected
                          origin: caller
                          result_counts:
                            web: 41
                      languages_searched:
                        - en
                    applied_request:
                      query: EU AI Act article 50 marking obligations
                      datasources:
                        - web
                      published_within_days: 365
                      undated: shown
                      safe_search: moderate
                      max_per_datasource: 10
                      ranking_order: relevance
                      max_candidates: 3
                      max_excerpt_characters: 600
                      max_total_characters: 40000
                      contents:
                        top: 1
                        max_characters: 8000
                        scope: main
                        summary: false
                      view: full
                      wait_seconds: 10
                      max_cost:
                        amount: '0.1000'
                        currency: USD
                      deterministic_only: false
                      pinned_version: 1.0.0
                      run_id: run_default
                      retention: hold
                    datasources_searched:
                      - id: web
                        display_name: Web
                        group: web
                        reason: default
                        outcome:
                          kind: delivered
                          reason: candidates
                        effective_country: DE
                        effective_language: en
                        wordings:
                          - 0
                        returned_count: 41
                        result_count: 41
                        result_count_kind: exact
                        lead_count: 3
                        filters_applied:
                          allowed_domains:
                            state: not_applicable
                          blocked_domains:
                            state: not_applicable
                          published_from:
                            state: not_applicable
                          published_until:
                            state: not_applicable
                          published_within_days:
                            state: native
                          undated:
                            state: emulated
                            how: pages without a detectable date kept, as asked
                          languages:
                            state: not_applicable
                          media_types:
                            state: not_applicable
                          safe_search:
                            state: native
                          source_kinds:
                            state: not_applicable
                          source_independence:
                            state: not_applicable
                          as_of_date:
                            state: not_applicable
                        operators_applied:
                          phrase:
                            state: not_applicable
                          exclusion:
                            state: not_applicable
                          alternatives:
                            state: not_applicable
                          site:
                            state: not_applicable
                          filetype:
                            state: not_applicable
                          intitle:
                            state: not_applicable
                          inurl:
                            state: not_applicable
                          before:
                            state: not_applicable
                          after:
                            state: not_applicable
                          wildcard:
                            state: not_applicable
                        access_used: open
                        cost:
                          ceiling:
                            amount: '0.0100'
                            currency: USD
                          actual:
                            amount: '0.0010'
                            currency: USD
                          units:
                            datasource_queries: 1
                          replayed: false
                    ranking:
                      reranked: true
                      reranker_version: rr-2026-10
                      min_score: 0.42
                      instructions_applied: false
                      priorities: []
                      order: relevance
                      preferred_domains: []
                      merge: stratified_rank_fusion
                      strata:
                        - datasource_id: web
                          language: en
                          lead_count: 3
                    execution:
                      version: 1.0.0
                      configuration: cfg-2026-11
                      models:
                        - step: reranking
                          version: rr-2026-10
                        - step: discovery
                          version: disc-2026-10
                      elapsed_seconds: 8.4
                    cost:
                      ceiling:
                        amount: '0.1000'
                        currency: USD
                      actual:
                        amount: '0.0200'
                        currency: USD
                      units:
                        searches: 1
                        datasource_queries: 1
                        model_steps: 2
                        contents: 1
                      replayed: false
                    searched_at: '2026-11-05T09:00:00Z'
                    run_id: run_default
                    expires_at: '2026-11-07T09:30:00Z'
                    request_id: req_02Bm6tTFlq4Fjkaic7g4OM
                    next_page_token: eyJzIjoic3JjaF80SG0iLCJvIjozfQ
        '400':
          $ref: '#/components/responses/Problem400'
        '401':
          $ref: '#/components/responses/Problem401'
        '403':
          $ref: '#/components/responses/Problem403'
        '404':
          $ref: '#/components/responses/Problem404'
        '410':
          $ref: '#/components/responses/Problem410'
        '429':
          $ref: '#/components/responses/Problem429'
        '500':
          $ref: '#/components/responses/Problem500'
        '503':
          $ref: '#/components/responses/Problem503'
components:
  parameters:
    Traceparent:
      name: traceparent
      in: header
      required: false
      description: >-
        Your own trace id for the call, the W3C Trace Context `traceparent`
        header, optional on every operation. getclean logs it with the call, so
        a request in your traces can be matched to its `Request-Id`, and never
        forwards it to a site or a source, a stated departure from W3C Trace
        Context section 3.4, which asks a vendor to pass it on. A malformed
        value is ignored, never refused, as the same recommendation asks.
      schema:
        type: string
  schemas:
    View:
      type: string
      description: >-
        How much of a search record comes back: `full`, every member, or
        `compact`, the smaller form the `Search` schema lists. A closed set.
      enum:
        - full
        - compact
    Search:
      type: object
      description: >-
        One search record, `srch_`, kept 48 hours after its last call and at
        most 30 days from its making. It keeps the results and the receipt as
        they were, and `get_search` pages the list the search stored and never
        searches again or charges. It reads in one order: the outcome; the
        notices and the coverage gaps, read before the list; the leads in rank
        order with the facts of each; the counts, which describe the search and
        never a page; how the question was read and the request as it ran; the
        receipt per source; what ordered the list; how it ran; the money.


        Under `view` `compact` only these members come, each whole: `id`,
        `outcome`, `notices`, `coverage_gaps`, `counts`, `end_reason`, `cost`,
        `searched_at`, `run_id`, `expires_at`, `request_id`, `next_page_token`
        on a paged `get_search`, and `candidates`, each with `id`, `url`,
        `title`, `published_date`, `access`, `relevance_score`,
        `source_profile`, `fetch_cost`, `dropped_reason` on a paged item,
        `excerpts` holding the first excerpt only, and `contents` when fetched.
        Every member outside that list is optional in this schema and always
        present in the full view.
      required:
        - id
        - outcome
        - notices
        - coverage_gaps
        - candidates
        - counts
        - cost
        - searched_at
        - run_id
        - expires_at
        - request_id
      properties:
        id:
          type: string
          pattern: ^srch_[A-Za-z0-9]{22}$
          description: >-
            The record's id, `srch_` and 22 random characters, which cannot be
            guessed.
          examples:
            - srch_4HmUunqCCXquleKVCosqFG
        retention:
          $ref: '#/components/schemas/Retention'
          description: >-
            How long the record is kept, `hold` or `none`. Present in the full
            view.
        outcome:
          $ref: '#/components/schemas/Outcome'
          description: >-
            What happened, first. `delivered` when every source tried answered
            and everything asked ran, a source skipped before work being a
            coverage gap and no partial; `partial` when something tried did not
            finish; the other kinds only when no source answered.
        notices:
          type: array
          description: >-
            Read before the list; a corrected query, an emulated filter, a cut,
            a default set by policy, a fetch that did not finish; a skipped
            source is a coverage gap, never a notice too. `[]` when none.
          items:
            $ref: '#/components/schemas/Notice'
        coverage_gaps:
          type: array
          description: What was asked and not searched, with why; `[]` when none.
          items:
            $ref: '#/components/schemas/CoverageGap'
        candidates:
          type: array
          description: >-
            The leads, in rank order; `[]` when none. On a later page of
            `get_search`, the list the search stored, each item with
            `dropped_reason`.
          items:
            $ref: '#/components/schemas/Candidate'
        counts:
          $ref: '#/components/schemas/SearchCounts'
          description: >-
            Leads returned and pages found before the cut; `found` equals
            `returned` plus every dropped count.
        end_reason:
          type: string
          description: >-
            Why the list ended: `relevance`, the next candidate fell under the
            ranking model's cut-off; `max_candidates`, the cap on leads was
            reached; `ceiling`, the money ran out; `exhausted`, every source
            gave all it had; `source_cap`, every source reached
            `max_per_datasource`. A closed set. Present on `delivered` and
            `partial`, absent on the other kinds.
          enum:
            - relevance
            - max_candidates
            - ceiling
            - exhausted
            - source_cap
        interpretation:
          $ref: '#/components/schemas/Interpretation'
          description: How the question was read. Present in the full view.
        applied_request:
          $ref: '#/components/schemas/SearchRequest'
          description: >-
            The request as it ran; every field whose value was in force present
            with that value, defaults and resolutions written out; a field with
            no value absent. Present in the full view.
        record:
          $ref: '#/components/schemas/SearchRecord'
          description: The search written up. Present only with `record_form`.
        datasources_searched:
          type: array
          description: The receipt per source. Present in the full view, `[]` when none.
          items:
            $ref: '#/components/schemas/DatasourceReceipt'
        ranking:
          $ref: '#/components/schemas/Ranking'
          description: What ordered the list. Present in the full view.
        execution:
          $ref: '#/components/schemas/Execution'
          description: >-
            How it ran; `models` carries `reranking`, `discovery` and
            `source_profile` when they ran. Present in the full view.
        cost:
          $ref: '#/components/schemas/Cost'
          description: >-
            The money, the original bill as stored on every `get_search` page,
            never a new charge; `units` among `searches`, `datasource_queries`,
            `model_steps` and the inline fetches' units.
        metadata:
          type: object
          description: Your own labels, returned as sent. Present when sent.
          additionalProperties:
            type: string
        searched_at:
          type: string
          format: date-time
          description: When the search started, RFC 3339 in UTC.
          examples:
            - '2026-11-05T09:00:00Z'
        run_id:
          type: string
          pattern: ^run_(default|[A-Za-z0-9]{22})$
          description: The run the record belongs to.
          examples:
            - run_default
        expires_at:
          type: string
          format: date-time
          description: >-
            When the record expires. This call moved it ahead, 48 hours from
            now, never past 30 days from the record's making; under `retention`
            `none` it is this answer's own moment. After that a call on the
            record is `410 search-expired` for 30 days, then `404`.
          examples:
            - '2026-11-07T09:00:03Z'
        request_id:
          type: string
          pattern: ^req_[A-Za-z0-9]{22}$
          description: This call's id, the same as the `Request-Id` header.
          examples:
            - req_02ARUKU1YFino5zjD2hYpX
        next_page_token:
          type: string
          maxLength: 1024
          description: >-
            The token for the next page of the list the search stored; pass it
            to `get_search` as `page_token`. Present only on a paged
            `get_search` while more remains, and a page that carries it always
            has at least one result.
    Retention:
      type: string
      description: >-
        How long a record is kept; `hold`, 48 hours after its last call and at
        most 30 days from its making, or `none`, nothing kept past the answer. A
        closed set.
      enum:
        - hold
        - none
    Outcome:
      type: object
      description: >-
        What happened to one piece of work, first in every answer. A record's
        outcome is the fact of the call that made it, and no later read rewrites
        it.
      required:
        - kind
        - reason
      properties:
        kind:
          type: string
          description: >-
            What kind of thing happened, one of five: `delivered`, everything
            asked for came, or the map of sections came in place of text that
            did not fit; `partial`, the work stopped in the middle and what was
            done is kept; `failed`, the source did not give a page; `refused`, a
            rule stopped the read; `needs_person`, a person must act before this
            can work. A closed set.
          enum:
            - delivered
            - partial
            - failed
            - refused
            - needs_person
        reason:
          type: string
          description: >-
            Why it happened. An open set whose published values are below; each
            line says what the reason means and what may work next, and
            `message` carries that sentence when the reason has one.


            The contents family, the record of one source:


            | Reason | Kind | Means | What may work next |

            |---|---|---|---|

            | `whole` | delivered | everything asked for fit | |

            | `sections_only` | delivered | the text did not fit
            `max_characters`, so the map of sections came instead |
            `get_section` on a row, free |

            | `matching_sections` | delivered | the text did not fit; the
            sections holding your highlights came | `get_section` for the rest |

            | `unchanged` | delivered | the page matches your
            `baseline_fingerprint`; no text is sent, the fetch's price is billed
            | |

            | `pages_failed` | partial | some pages of a document could not be
            parsed; `pages.failed_pages` names them | |

            | `cost_capped` | partial | the parse stopped at `max_cost`, the
            key's cap or the balance; `message` says which | a larger
            `max_cost`, or the account owner funds the account or raises the cap
            |

            | `budget_capped` | partial | the parse stopped at the run's or the
            key's budget | the account owner raises the budget |

            | `time_capped` | partial | a document at a URL did not finish
            within `wait_seconds`, or a job passed its bound | `upload_contents`
            with the `url`, which parses it whole as a job |

            | `canceled` | partial | the job was canceled with pages already
            parsed; they are kept | |

            | `dns_timeout`, `connection_refused`, `connection_timeout`,
            `connection_terminated`, `tls_protocol_error`,
            `http_response_timeout`, `http_response_incomplete` | failed | the
            fetch failed on the way to the site, named as RFC 9209 names it | a
            retry later may work |

            | `dns_error`, `tls_certificate_error` | failed | the site's name
            did not resolve, or its certificate failed | the same request will
            not work |

            | `not_found` | failed | the site answered 404 or 410 | the same
            request will not work |

            | `access_denied` | failed | the site answered 401 or 403 | the same
            request will not work |

            | `payment_required` | failed | the site asked a price at the
            request, or answered 402, and no `max_source_price` covered it;
            `cost.source_price` is the price asked | a `max_source_price` |

            | `rate_limited` | failed | the site answered 429 | a retry later
            may work |

            | `server_error` | failed | the site answered 5xx | a retry later
            may work |

            | `http_error` | failed | another status that is not a page | the
            same request will not work |

            | `challenge_served` | failed | a bot challenge stood where the page
            should be | a retry later may work on sites that do not challenge
            every new visitor; or a person opens the URL and uploads the saved
            page with `captured_url` |

            | `blocked` | failed | the site refused the visitor with a block
            page | the same request will not work |

            | `region_restricted` | failed | the page says it is not offered in
            the visitor's country | another `subject_country` |

            | `deadline` | failed | nothing readable by `wait_seconds` | a
            larger `wait_seconds` |

            | `empty` | failed | no text, no links and nothing to recognize |
            the same request will not work |

            | `corrupt_document` | failed | the document could not be opened |
            the same request will not work |

            | `no_history` | failed | no archive copy at or before the end of
            `as_of_date`; `source.archives_consulted` names the archives asked |
            the same date will not work |

            | `too_large` | refused | the page or document passed the largest
            size taken whole; for a document, `pages.count` and the outline
            still come | the same request will not work |

            | `destination_refused` | refused | the address resolved to, or a
            redirect reached, a place that is not globally reachable | the same
            request will not work |

            | `domain_not_allowed` | refused | a redirect reached a host outside
            the key's domain policy | the same request will not work under this
            key's policy |

            | `unsupported_media_type` | refused | a document type not taken, a
            container or a media file; or, on the upload, a `url` that serves a
            web page, where `fetch_contents` is the call | the same request will
            not work |

            | `password_protected` | refused | the document is locked | a person
            with the password |

            | `robots_disallowed` | refused | the site's robots file forbids
            getclean by its published name | the same request will not work |

            | `robots_unreachable` | refused | the robots file answered 5xx or
            not at all, which RFC 9309 reads as a full disallow | a retry later
            may work |

            | `legal_block` | refused | the site answered 451;
            `source.blocked_by` carries its link | another source, never another
            `subject_country` |

            | `sign_in_needed` | needs_person | a sign-in page stood where the
            page should be | a person signs in and uploads the saved page with
            `captured_url` |

            | `paywalled` | needs_person | a purchase wall stood where the page
            should be | a person |


            The search family, the search as a whole and each source's receipt:


            | Reason | Kind | Means | What may work next |

            |---|---|---|---|

            | `candidates` | delivered | one or more results | |

            | `none` | delivered | nothing matched; the receipt says what was
            searched | other wordings |

            | `corrected_question` | delivered | every result came for a wording
            getclean corrected; `interpretation.wordings` shows the correction |
            |

            | `sources_missing` | partial | a source or a wording gave no list
            while others did | a retry later may work for that source |

            | `rerank_missing` | partial | the deadline or the ceiling cut the
            reranking; the merged order came and `relevance_score` is null | a
            larger `wait_seconds` or `max_cost` |

            | `fetches_missing` | partial | some inline fetches did not finish
            or were cut; the notice `fetch_not_finished` names the candidates |
            `fetch_contents` on each |

            | `not_accepted_by_source` | failed | every source refused the
            question as written; a source's own words stand in `source_text` |
            another wording |

            | `source_unreachable` | failed | every source was down | a retry
            later may work |

            | `login_expired` | needs_person | a registered login expired | the
            account owner renews the login |

            | `fee_through_form` | needs_person | the source charges only
            through a form | a person |


            In a source's receipt, `datasources_searched[].outcome`, the failed
            reasons of the first table name what happened to that one source,
            with `deadline` for a source that had not answered at `wait_seconds`
            and `payment_required` for a fee above `max_source_price`;
            `legal_block` and `domain_not_allowed` refuse a source withheld by
            law or outside the key's domain policy.
          examples:
            - whole
            - sections_only
            - matching_sections
            - unchanged
            - pages_failed
            - cost_capped
            - budget_capped
            - time_capped
            - canceled
            - dns_error
            - dns_timeout
            - connection_refused
            - connection_timeout
            - connection_terminated
            - tls_protocol_error
            - tls_certificate_error
            - http_response_timeout
            - http_response_incomplete
            - not_found
            - access_denied
            - payment_required
            - rate_limited
            - server_error
            - http_error
            - challenge_served
            - blocked
            - region_restricted
            - deadline
            - empty
            - corrupt_document
            - no_history
            - too_large
            - destination_refused
            - domain_not_allowed
            - unsupported_media_type
            - password_protected
            - robots_disallowed
            - robots_unreachable
            - legal_block
            - sign_in_needed
            - paywalled
            - candidates
            - none
            - corrected_question
            - sources_missing
            - rerank_missing
            - fetches_missing
            - not_accepted_by_source
            - source_unreachable
            - login_expired
            - fee_through_form
        message:
          type: string
          description: >-
            One sentence with the particulars a reason has, the limit that
            stopped the work, the protocol that asked a price, the operation to
            use instead, and on a reason that has retry guidance, that
            guidance's sentence. Present when the reason has any.
    Notice:
      type: object
      description: >-
        A fact to read before the result, never an error: something was cut,
        left out, replaced or found that changes how you read what follows.
      required:
        - code
        - message
      properties:
        code:
          type: string
          description: >-
            What the notice tells you; an open set whose published values are
            below. A notice kept with the record is a fact of the record and
            comes back first on every answer about it, with `held` true; the
            others belong to this answer alone.


            | Code | Made by | Means |

            |---|---|---|

            | `highlight_not_found` | the fetch, the upload, the batch,
            `highlight_contents` | one of your `highlights` strings was not
            found and nothing bears on it, or `deterministic_only` kept the
            judging step out; one notice per string, `pointer` naming it, as
            `/highlights/2`; kept when the fetch made it |

            | `highlights_cut` | the same | more than 50 occurrences were found;
            the first 50 in document order came; kept |

            | `sections_cut` | the fetch, the upload, the batch, `get_contents`,
            `get_section` | levels of the map were left out; `get_section` lists
            them |

            | `links_cut` | the same | the link index was cut at 1,000, or in a
            batch by `max_total_characters`; `list_links` has the rest |

            | `total_characters_cut` | the batch, the search's inline fetch |
            this record came as `sections_only` because the whole answer's text
            bound was reached; `get_contents` returns its text free unless
            `retention` is `none` |

            | `hidden_text_cut` | the fetch, the upload, the batch | a hidden
            text item was cut at 1,000 characters, or the list at 50 items; kept
            |

            | `structured_data_cut` | the same | the page's structured data
            passed 64 KB; kept |

            | `block_over_limit` | `list_blocks` | one block larger than
            `max_characters` came whole, alone on its page |

            | `page_size_lowered` | every paged answer | `page_size` was above
            the maximum and was lowered, never refused |

            | `size_limit` | the fetch, the upload, the batch | the page or
            document passed the largest size taken whole, so the outcome is
            `too_large`; kept |

            | `conversion_mismatch` | the same | getclean's own check of the
            text against the page did not pass, so read the content with care;
            the message carries the two overlap figures it compared; kept |

            | `ad_blocker_failed` | the fetch, the batch | the advertising
            filter did not run on this read, so advertising may stand among the
            content; kept |

            | `not_settled` | the fetch, the batch | the page was still changing
            when `wait_seconds` ran out and was measured as it stood; kept |

            | `unread_region` | the fetch, the upload, the batch | a region that
            cannot be read as text covers part of the main content; the message
            names its kind and size; kept |

            | `no_main_content` | the same | no main content was found, so the
            whole page came under `scope: whole_page`; kept |

            | `paywall_declared` | the fetch, the batch, an uploaded HTML file;
            repeated by `compare_contents` | the page declares its content not
            free, so what came may be a teaser; kept |

            | `redirected` | the fetch, the upload by `url`, the batch | the
            final URL differs from the one asked beyond the scheme, the host's
            case, a trailing slash and tracking parameters; kept |

            | `requests_blocked` | the fetch, the batch | the page's own
            requests to addresses that are not globally reachable were blocked
            and the page went on; the count in the message; kept |

            | `field_not_applicable` | the fetches, the reads of a record, the
            model steps, the search | a field did not apply to this work and was
            left out; `field` names it |

            | `cost_cut` | the fetch, the upload, the batch,
            `highlight_contents` | an extra was cut by `max_cost`, the key's cap
            or the balance; the message says which, `field` names the extra;
            kept on a record |

            | `budget_cut` | the same | an extra was cut by the run's or the
            key's budget; the message says which; kept on a record |

            | `time_cut` | the fetch, the upload, the batch | a model step or
            the screenshot was cut by `wait_seconds` and not billed; kept |

            | `step_failed` | the fetch, the upload, the batch,
            `highlight_contents` | a model step or the screenshot failed or
            passed its bound and was not billed; kept |

            | `model_link_removed` | the fetch, the upload, the batch,
            `fill_schema`, `summarize_contents` | a link or an image a model
            wrote was removed from `summary` or `schema_values`; kept |

            | `recognition_uncertain` | the fetch, the upload, the batch | pages
            were recognized below the published confidence bar; the message
            names them; kept |

            | `tracked_changes` | the same | the document carries tracked
            changes, shown as accepted; the count in the message; kept |

            | `upload_to_finish` | the fetch, the batch | a document at a URL
            was cut by time; `upload_contents` with the `url` parses it whole as
            a job; kept |

            | `fingerprint_incomparable` | the fetch, the upload, the batch,
            `compare_contents` | the fingerprint came from another `scope`,
            version, configuration or kind of source, so the fetch ran whole; on
            a comparison, the kind of source or the configuration differs and
            the comparison ran; kept on a fetch's or a batch's record |

            | `fingerprint_unknown` | the fetch, the upload, the batch | the
            `baseline_fingerprint` matches no record this account keeps, so the
            fetch ran whole at the full price; kept |

            | `marks_not_read` | the same | the document carries no structure
            for its formatting, so bold, italics and strikethroughs could not be
            read; kept |

            | `content_not_rendered` | the same | a page holds handwriting, a
            drawing, a formula without structure or a blacked-out region, which
            came flattened or not at all; a published code this version does not
            make, such content coming with no notice and `pages.pictured`
            staying `[]` |

            | `archive_unreachable` | the fetch, the batch | an archive did not
            answer the as-of lookup, so `archives_consulted` lacks it; kept |

            | `default_set_by_policy` | the fetch, the upload, the batch,
            `highlight_contents`, the search | a default was replaced by the
            key's policy, as `deterministic_only` under a policy that forbids
            model work; kept on a record and on a search |

            | `version_retiring` | every answer with notices, except a job, the
            job list and the catalog | the answer was made under a version
            within `bounds.contents.version_notice_days` of its retirement |

            | `characters_removed` | the MCP server only | invisible characters,
            markup comments or hidden words were removed from the text, so the
            cleaned text no longer hashes to `fingerprint` |

            | `query_corrected` | the search, the search batch | a corrected
            wording ran beside or instead of yours; `interpretation.wordings`
            shows it; kept |

            | `filter_emulated` | the same | a source without a filter had it
            applied afterwards by getclean; the message says how; kept |

            | `window_after_as_of_date` | the same | `published_from` begins
            after `as_of_date`, so no page can match; kept |

            | `fetch_not_finished` | the same | an inline fetch was not started
            by the deadline, or its URL is one the key's policy refuses, so its
            candidate carries no record; kept |
          examples:
            - highlight_not_found
            - highlights_cut
            - sections_cut
            - links_cut
            - total_characters_cut
            - hidden_text_cut
            - structured_data_cut
            - block_over_limit
            - page_size_lowered
            - size_limit
            - conversion_mismatch
            - ad_blocker_failed
            - not_settled
            - unread_region
            - no_main_content
            - paywall_declared
            - redirected
            - requests_blocked
            - field_not_applicable
            - cost_cut
            - budget_cut
            - time_cut
            - step_failed
            - model_link_removed
            - recognition_uncertain
            - tracked_changes
            - upload_to_finish
            - fingerprint_incomparable
            - fingerprint_unknown
            - marks_not_read
            - content_not_rendered
            - archive_unreachable
            - default_set_by_policy
            - version_retiring
            - characters_removed
            - query_corrected
            - filter_emulated
            - window_after_as_of_date
            - fetch_not_finished
        message:
          type: string
          description: >-
            One sentence with the particulars: what was cut, by which limit, how
            much, or where.
        field:
          type: string
          description: The request field the notice is about. Present when there is one.
        pointer:
          type: string
          format: json-pointer
          description: >-
            A JSON Pointer into the request the notice answers: the fetch's
            request for a notice kept with the record, this call's for its own.
            Present when there is one.
          examples:
            - /highlights/1
        datasource_id:
          type: string
          pattern: ^[a-z][a-z0-9_]{0,63}$
          description: The source the notice is about. Present on a search only.
          examples:
            - web
        held:
          type: boolean
          description: >-
            True on a notice kept with the record, a fact of the work that comes
            back on every later answer about it. On the fetch's own answer every
            notice is that answer's own, so none carries it; absent on a notice
            that belongs to this answer alone.
    CoverageGap:
      type: object
      description: >-
        One thing asked and not searched at all, with why; the receipt's outcome
        names what happened to a source that was tried.
      required:
        - target_kind
        - target
        - reason
      properties:
        target_kind:
          type: string
          description: >-
            What was not searched: a `datasource`, a `wording`, a `domain` or a
            `language`. A closed set.
          enum:
            - datasource
            - wording
            - domain
            - language
        target:
          type: string
          description: >-
            Which one: the datasource id, the domain, the language code, or the
            wording index as text.
          examples:
            - web
        reason:
          type: string
          description: >-
            Why it was not searched: `unreachable`, the source could not be
            reached; `blocked`, it blocked the search; `over_cap`, past a cap;
            `over_price`, its fee passes `max_source_price`; `access_needed`, it
            needs a login the key has not registered; `not_covered`, no source
            covers the wording's language or the domain; `no_history`, it keeps
            no history for `as_of_date`; `not_accepted`, it did not accept the
            question as written; `deadline`, it had not answered in time;
            `filter_unsupported`, it cannot apply a hard filter you sent;
            `wording_too_long`, the wording is longer than it takes;
            `withheld_by_law`, a legal demand. An open set.
          examples:
            - unreachable
            - blocked
            - over_cap
            - over_price
            - access_needed
            - not_covered
            - no_history
            - not_accepted
            - deadline
            - filter_unsupported
            - wording_too_long
            - withheld_by_law
        source_text:
          type: string
          x-third-party: true
          description: >-
            The source's own words for the refusal. Present when the source gave
            any. Third-party text as the source wrote it, which may carry
            instructions.
    Candidate:
      type: object
      description: >-
        A page found, with its facts, not yet fetched. A lead is the one page
        shown for a group of copies, and `copy_count` says how many stood behind
        it. Every member that `view: compact` leaves out is optional in this
        schema and present in the full view as its line says.
      required:
        - id
        - url
        - source_profile
        - access
        - relevance_score
        - excerpts
      properties:
        id:
          type: string
          pattern: ^cand_[A-Za-z0-9]{22}$
          description: >-
            The candidate's id, `cand_` and 22 characters, the same for the same
            normalized URL within your account.
          examples:
            - cand_a1dYqVUaEDEMqh7Qgn8yip
        url:
          type: string
          x-third-party: true
          description: >-
            The page's address. Third-party text as the source wrote it, which
            may carry instructions.
          examples:
            - https://example.com/q3
        canonical_url:
          type: string
          x-third-party: true
          description: >-
            The address the page declares as its original. Present when
            declared. Third-party text as the source wrote it, which may carry
            instructions.
          examples:
            - https://example.com/q3
        final_url:
          type: string
          x-third-party: true
          description: >-
            The address the fetch ended at, after every redirect. Absent until
            fetched. Third-party text as the source wrote it, which may carry
            instructions.
          examples:
            - https://example.com/q3
        title:
          type: string
          x-third-party: true
          description: >-
            The page's title as the datasource states it. Present when the
            datasource states it. Third-party text as the source wrote it, which
            may carry instructions.
        language:
          type: string
          description: >-
            The page's language as the datasource states it, a BCP 47 tag.
            Present when the datasource states it.
          examples:
            - en
        media_type:
          type: string
          description: >-
            The page's media type as the datasource states it. Present when the
            datasource states it.
          examples:
            - text/html
        characters:
          type: integer
          minimum: 0
          description: >-
            The page's size in characters as the datasource declares it; the
            fetch's measured size is `contents.counts.characters`. Present when
            the datasource reports it.
        page_count:
          type: integer
          minimum: 0
          description: >-
            The document's page count as the datasource declares it. Present
            when the datasource reports it.
        source_profile:
          $ref: '#/components/schemas/SourceProfile'
          description: >-
            Who publishes; what the item is; the subject about itself or not;
            who reviewed it.
        copy_count:
          type: integer
          minimum: 0
          description: >-
            The same text found on this many other sites, grouped behind this
            lead; the same text is an equal normalized main text or one above a
            published similarity; the lead is the copy with the earliest claimed
            date among the copies that carry one, else the first found. Present
            in the full view.
        language_versions:
          type: array
          description: >-
            The page's own translations as declared; `[]` when none. Present in
            the full view.
          items:
            $ref: '#/components/schemas/LanguageVersion'
        carrier:
          type: string
          description: >-
            The kind of source: `web`, a live page, or `archive`, an archive's
            copy read under `as_of_date`; an open set; a candidate never carries
            `upload`. Present in the full view.
          examples:
            - web
            - archive
        published_date:
          type: string
          format: date
          description: >-
            The date of publication the page or the datasource claims, a full
            date. Present when one states it.
        published_date_basis:
          type: string
          description: >-
            Where the date was read: `structured_data`, `meta_tag`, `byline`,
            `url` or `datasource`; an open set. Present with the date.
          examples:
            - structured_data
            - meta_tag
            - byline
            - url
            - datasource
        published_date_precision:
          $ref: '#/components/schemas/DatePrecision'
          description: >-
            How exact the date is, `day`, `month` or `year`. Present with the
            date.
        modified_date:
          type: string
          format: date
          description: >-
            The date of the last change the page or the datasource claims, a
            full date. Present when one states it.
        modified_date_basis:
          type: string
          description: >-
            Where the modification date was read: `structured_data`, `meta_tag`,
            `byline`, `url` or `datasource`; an open set. Present with the date.
          examples:
            - structured_data
            - meta_tag
            - byline
            - url
            - datasource
        published_at:
          type: string
          format: date-time
          description: >-
            The moment of publication in UTC. Present only when the page states
            a time with its zone.
        modified_at:
          type: string
          format: date-time
          description: >-
            The moment of the last change in UTC. Present only when the page
            states a time with its zone.
        acquired_at:
          type: string
          format: date-time
          description: When the datasource took its copy of the page. Present when known.
        declared:
          $ref: '#/components/schemas/Declared'
          description: >-
            What the datasource declares about the item. Present when the
            datasource declares anything.
        access:
          $ref: '#/components/schemas/Access'
          description: What the page demands, seen without a fetch.
        identifier_matches:
          type: array
          description: >-
            The codes sent that this page carries; `[]` when none. Present in
            the full view.
          items:
            $ref: '#/components/schemas/SubjectIdentifier'
        relevance_score:
          type:
            - number
            - 'null'
          minimum: 0
          maximum: 1
          description: >-
            The ranking model's score, 0 to 1; null under `deterministic_only`
            and on `rerank_missing`.
        dropped_reason:
          type: string
          description: >-
            Why this item is not a lead, one of the member names of
            `DroppedCounts`. A closed set. Absent on a lead; set on an item of a
            later page of `get_search`.
          enum:
            - not_relevant
            - undated
            - max_per_domain
            - blocked_domain
            - outside_allowed
            - source_kind
            - source_independence
            - folded_copy
            - phrase_check
            - exclusion_check
            - beyond_max_candidates
        lead_id:
          type: string
          pattern: ^cand_[A-Za-z0-9]{22}$
          description: >-
            The lead this copy was grouped behind. Present on an item of a later
            page dropped as `folded_copy`.
          examples:
            - cand_a27BTvL7IEwl2lokVFjz6n
        excerpts:
          type: array
          description: >-
            The matching snippets; `[]` when none; under `view` `compact` the
            first excerpt only.
          items:
            $ref: '#/components/schemas/Excerpt'
        matches:
          type: array
          description: Which wording found it where. Present in the full view only.
          items:
            $ref: '#/components/schemas/Match'
        fetch_cost:
          $ref: '#/components/schemas/Money'
          description: >-
            The most a fetch of it with this request's inline options can cost,
            from the price list and the known size. Absent when a document's
            page count is unknown.
        contents:
          $ref: '#/components/schemas/ContentsCompact'
          description: >-
            The compact record of the inline fetch, with its own `cost`; the
            full record is free through `get_contents` with its `id`. Present
            when the search that made the record fetched it, in both views and
            on `get_search`'s first page.
    SearchCounts:
      type: object
      description: >-
        The counts describe the search, never a page; `found` equals `returned`
        plus every dropped count whatever ended the list.
      required:
        - returned
        - found
        - dropped
      properties:
        returned:
          type: integer
          minimum: 0
          description: The leads returned.
        found:
          type: integer
          minimum: 0
          description: The pages found before the cut.
        dropped:
          $ref: '#/components/schemas/DroppedCounts'
          description: Why the rest are not leads, by reason.
    Interpretation:
      type: object
      description: How the question was read; every list present, `[]` when empty.
      required:
        - canonical_query
        - phrases
        - exclusions
        - operators
        - wordings
        - languages_searched
      properties:
        canonical_query:
          type: string
          description: >-
            The question as getclean read it; with no `query`, the identifiers'
            values joined by a space.
          examples:
            - EU AI Act article 50 marking obligations
        phrases:
          type: array
          description: The quoted phrases.
          items:
            type: string
        exclusions:
          type: array
          description: The excluded words.
          items:
            type: string
        operators:
          type: array
          description: The operators read from the question.
          items:
            $ref: '#/components/schemas/QueryOperator'
        wordings:
          type: array
          description: Every wording that ran, with its origin.
          items:
            $ref: '#/components/schemas/Wording'
        languages_searched:
          type: array
          description: The languages the wordings ran in, BCP 47 tags.
          items:
            type: string
            examples:
              - en
    SearchRequest:
      type: object
      description: >-
        The request of `search`; also the shape of `Search.applied_request`, the
        request as it ran with every field in force. Every field is at the top
        level but the named objects `Money`, `SubjectIdentifier` and
        `SearchContentsOptions`; an explicit null equals an absent field and
        gets the default. The object is closed; an unknown field is refused
        `invalid-field`, `unknown_field`.
      additionalProperties: false
      properties:
        query:
          type: string
          minLength: 1
          maxLength: 2000
          description: >-
            The question, 1 to 2,000 characters; required unless
            `subject_identifiers` is sent. `"phrase"`, `-word`, `OR`, one level
            of `( )`, `site:`, `filetype:`, `intitle:`, `inurl:`, `before:`,
            `after:` and `*` are honored where a source supports them, and the
            receipt's `operators_applied` says what each source did with each.
          examples:
            - EU AI Act article 50 marking obligations
        alternate_queries:
          type: array
          maxItems: 10
          uniqueItems: true
          description: >-
            Other wordings of the question, in any language, each 1 to 2,000
            characters, up to 10; one merged list with `query`, 20 wordings at
            most after OR splits. Default none. A wording runs only on the
            sources that cover its language; nothing is translated, so a wording
            in another language reaches the sources in that language. Without
            `query` it is refused `dependent`.
          items:
            type: string
            minLength: 1
            maxLength: 2000
        subject_identifiers:
          type: array
          maxItems: 10
          uniqueItems: true
          description: >-
            Exact codes of the subject, up to 10 `SubjectIdentifier` objects;
            with no `query`, each identifier's value runs as a wording with
            origin `identifier`. `issuer` is required for `ticker`, `docket`,
            `tax_id` and `registry`, as the catalog's codes; a duplicate is
            refused `duplicate`. Default none.
          items:
            $ref: '#/components/schemas/SubjectIdentifier'
        subject_country:
          type: string
          pattern: ^[A-Z]{2}$
          description: >-
            The country the search is made from, ISO 3166-1 alpha-2; groups of
            sources expand by it; the inline fetch reads from it when it is a
            country getclean can read from, one of `Limits.exits`, else from the
            key's `default_exit` with the notice `field_not_applicable`. Default
            none.
          examples:
            - DE
        purpose:
          type: string
          minLength: 1
          maxLength: 2000
          description: >-
            Your reason for the search, kept in the record and read by every
            model step; never sent to a source. At most 2,000 characters.
            Default none.
        datasources:
          type: array
          maxItems: 10
          uniqueItems: true
          description: >-
            Where to search: up to 10 of a datasource id, a group, or
            `set:NAME`, a published set, each 1 to 64 characters; these are
            names without dots, where `allowed_domains` takes site names with
            dots. When sent, the search runs on these plus the sources that
            resolve a scheme of your `subject_identifiers`, added without a
            model step, each in the receipt with reason `identifier`. When
            absent, it runs on `web` plus the groups a model chooses for the
            question, one model step, each named; under `deterministic_only`, on
            `web` only. An unknown id is `datasource-unknown`, an unknown set
            `domain-set-unknown`, a site name here `misplaced`.
          items:
            type: string
            minLength: 1
            maxLength: 64
            examples:
              - web
              - courtlistener
        allowed_domains:
          type: array
          maxItems: 500
          uniqueItems: true
          description: >-
            Only results on these sites count, site names with dots: up to 500
            of a domain, a wildcard such as `*.example.com`, a URL prefix, a
            suffix such as `.gov`, or `set:NAME`, a published set, each 1 to
            2,048 characters. What each form reaches: a domain, that host and
            every host under it; `*.example.com`, the hosts under the domain and
            not the domain itself; a URL prefix, every address that begins with
            it; a suffix with a leading dot, every domain that ends in it;
            `set:NAME`, the sites of that set. It may narrow the key's
            `policy.allowed_domains` and never widen it, which is
            `policy-limit-exceeded`. Default none. A site in both this and
            `blocked_domains` is refused `exclusive`; a datasource id here
            `misplaced`.
          items:
            type: string
            minLength: 1
            maxLength: 2048
        blocked_domains:
          type: array
          maxItems: 500
          uniqueItems: true
          description: >-
            Never results on these sites; up to 500 of the same forms and bound
            as `allowed_domains`, each form reaching what it reaches there.
            Default none.
          items:
            type: string
            minLength: 1
            maxLength: 2048
        published_from:
          type: string
          format: date
          description: >-
            Pages published on or after this date, inclusive, by the page's own
            date. Default none. With `published_within_days` it is refused
            `exclusive`; after `published_until` the pair is refused `order`; a
            date after today `bound`; a window that begins after `as_of_date`
            makes the notice `window_after_as_of_date`.
          examples:
            - '2026-01-01'
        published_until:
          type: string
          format: date
          description: Pages published on or before this date, inclusive. Default none.
          examples:
            - '2026-11-01'
        published_within_days:
          type: integer
          minimum: 1
          maximum: 3650
          description: >-
            Pages published within this many days counted back from today, or
            from `as_of_date` when it is sent; 1 to 3,650. Not with
            `published_from` or `published_until`, which is refused `exclusive`.
            Default none.
        undated:
          $ref: '#/components/schemas/Undated'
          default: shown
          description: >-
            Whether pages with no detectable date are kept inside a date window:
            `shown` keeps them, `hidden` drops them. Default `shown`. Sent
            without a window it makes the notice `field_not_applicable`.
        languages:
          type: array
          maxItems: 10
          uniqueItems: true
          description: >-
            Only pages written in these languages, up to 10 BCP 47 tags, each 1
            to 35 characters; what the pages are written in, independent of the
            wordings' languages. Default none.
          items:
            type: string
            minLength: 1
            maxLength: 35
        media_types:
          type: array
          maxItems: 10
          uniqueItems: true
          description: >-
            Only these file types, up to 10 IANA media types, each 1 to 255
            characters; a bare `pdf` is refused `not_allowed` with
            `application/pdf` suggested. Default none.
          items:
            type: string
            minLength: 1
            maxLength: 255
            examples:
              - application/pdf
        safe_search:
          $ref: '#/components/schemas/SafeSearch'
          default: moderate
          description: >-
            How strictly adult content is filtered: `off`, `moderate` or
            `strict`. Where a source has the setting it is mapped to the nearest
            level, said with the notice `filter_emulated`; it never removes a
            source. Never looser than the key's `policy.safe_search`, which is
            `policy-limit-exceeded`. Default `moderate`.
        source_kinds:
          type: array
          minItems: 1
          maxItems: 24
          uniqueItems: true
          description: >-
            Only these kinds of publisher, 1 to 24 of the kinds of
            `SourceProfile.kind`, never `unknown`; a filter that removes, where
            `ranking_priorities` only reorders. Default none.
          items:
            type: string
            minLength: 1
            description: One publisher kind, a value of `SourceProfile.kind`.
            examples:
              - state
              - court
              - regulator
              - statistics_office
              - intergovernmental
              - standards_body
              - academic
              - scholarly_publisher
              - archive
              - reference
              - press
              - information_provider
              - company
              - professional_practice
              - trade_body
              - marketplace
              - civil_society
              - political
              - religious
              - education
              - healthcare
              - cultural
              - individual
              - community
        source_independence:
          $ref: '#/components/schemas/SourceIndependence'
          description: >-
            Only sources independent of the subject, or only its own;
            `independent` or `self`. Needs a subject resolved from
            `subject_identifiers`, else the notice `field_not_applicable`.
            Default none, any.
        as_of_date:
          type: string
          format: date
          description: >-
            Search each source as it stood at the end of that day, UTC, and read
            any inline fetch from an archive's copy of that day. A date not
            after today. Default none, the sources as they stand now. A source
            that keeps no history reports `no_history`.
          examples:
            - '2026-10-01'
        max_per_datasource:
          type: integer
          minimum: 1
          maximum: 100
          default: 10
          description: >-
            Results taken from each source per wording, before merging; capped
            by the source's maximum. 1 to 100; default 10.
        ranking_instructions:
          type: string
          minLength: 1
          maxLength: 2000
          description: >-
            Your instructions to the ranking model, at most 2,000 characters;
            kept in the record. Default none. Refused `model-work-refused` under
            `deterministic_only`.
        ranking_priorities:
          type: array
          maxItems: 4
          uniqueItems: true
          description: >-
            Source facts that go first, in this order, up to 4 of `official`,
            `independent`, `primary`, `reviewed`; the leads grouped by them,
            then ordered within each group by `ranking_order`. Default none.
            `independent` with no subject resolved makes the notice
            `field_not_applicable`.
          items:
            $ref: '#/components/schemas/RankingPriority'
        ranking_order:
          $ref: '#/components/schemas/RankingOrder'
          default: relevance
          description: >-
            The order within each priority group; `relevance`, `newest` or
            `oldest`; undated pages last under the date orders; the relevance
            cut-off applies in every case. Default `relevance`.
        ranking_preferred_domains:
          type: array
          maxItems: 500
          uniqueItems: true
          description: >-
            Sites ranked first among results of equal relevance; other sites
            still count. Up to 500 of the forms of `allowed_domains`, each
            reaching what it reaches there, each 1 to 2,048 characters. Default
            none. A value outside `allowed_domains` when it is set, or in
            `blocked_domains`, is refused `dependent`.
          items:
            type: string
            minLength: 1
            maxLength: 2048
        ranking_max_per_domain:
          type: integer
          minimum: 1
          maximum: 50
          description: >-
            The most leads kept from one site in the answer, 1 to 50. Default
            none. With one allowed site it makes the notice
            `field_not_applicable`.
        max_candidates:
          type: integer
          minimum: 1
          maximum: 50
          default: 10
          description: >-
            The leads returned, 1 to 50; default 10. The results past them are
            read free by `get_search`.
        max_excerpt_characters:
          type: integer
          minimum: 0
          maximum: 4000
          default: 600
          description: >-
            The excerpt per lead, in characters, 0 to 4,000; 0 means none.
            Default 600.
        max_total_characters:
          type: integer
          minimum: 1000
          maximum: 200000
          default: 40000
          description: >-
            The whole answer's text, excerpts and fetched pages together, 1,000
            to 200,000; the excerpts first, cut from the last lead backwards
            when they alone pass it, then the fetched pages in rank order while
            they fit in what remains, a page that would pass it coming as
            `sections_only`; each cut the notice `total_characters_cut`. Default
            40,000. Below `max_excerpt_characters` it is refused `order`.
        contents:
          $ref: '#/components/schemas/SearchContentsOptions'
          description: >-
            Fetch this many top leads in the same call, under the inline fetch's
            rules; `contents.max_characters` bounds one page,
            `max_total_characters` the whole answer. Default none. The options
            without `top` are refused `required`; `top` above `max_candidates`
            `order`; with `wait_seconds` below 5, the least a fetch needs,
            `order`.
        view:
          $ref: '#/components/schemas/View'
          default: full
          description: >-
            How much of the record comes back: `full`, every member, or
            `compact`, the smaller form the `Search` schema lists. Default
            `full`; the MCP server always asks for `compact`.
        wait_seconds:
          type: number
          minimum: 0.2
          maximum: 60
          default: 10
          description: >-
            The most seconds this call may work, the ranking, the choice of
            sources and every inline fetch inside, counted from the start of the
            work; what did not finish comes back `partial`, named. 0.2 to 60;
            default 10.
        max_cost:
          $ref: '#/components/schemas/Money'
          description: >-
            The most this call may cost, in the account's currency. When it
            cannot cover everything, the extras are cut in order, each with the
            notice `cost_cut`: first each inline fetch's own extras, then whole
            fetches, then the ranking, then the choice of sources, then the
            results taken per source. Default the key's cap on one call. Below
            the smallest call's price, one `searches` and one
            `datasource_queries`, it is refused `cost-exceeds-cap` with
            `minimum_cap`.
        deterministic_only:
          type: boolean
          default: false
          description: >-
            Turn off every step a model judges: the ranking and the choice of
            sources, which the answer then says; the publisher's kind only from
            what getclean already knows; the inline fetch's `json_schema` and
            `summary` refused by name and its `highlights` found verbatim only.
            Text recognition on a scanned page fetched inline still runs and is
            listed. Default false. Sending false under a key whose policy
            forbids model work is `policy-limit-exceeded`.
        pinned_version:
          type: string
          minLength: 1
          maxLength: 64
          description: >-
            The version of getclean to run under, at most 64 characters. Default
            the current version. A version not served is `version-withdrawn`.
          examples:
            - 1.0.0
        run_id:
          type: string
          pattern: ^run_(default|[A-Za-z0-9]{22})$
          default: run_default
          description: >-
            The run the record belongs to, an existing run of the key. Default
            the key's default run. An unknown run is refused `not_allowed`.
        record_form:
          type: string
          minLength: 1
          description: >-
            Have the search written up for a reviewer: `plain`, in plain words,
            or `prisma`, in the PRISMA form a systematic review reports; an open
            set. Default none, no write-up.
          examples:
            - plain
            - prisma
        metadata:
          type: object
          minProperties: 1
          maxProperties: 20
          propertyNames:
            minLength: 1
            maxLength: 64
          additionalProperties:
            type: string
            minLength: 1
            maxLength: 512
          description: >-
            Your own labels, returned on the record as sent and never passed to
            a source: at most 20 string pairs, keys of 1 to 64 characters,
            values of 1 to 512. Default none. An empty map is refused `bound`.
        max_source_price:
          $ref: '#/components/schemas/Money'
          description: >-
            The most you allow for a datasource that charges per query, or for a
            site an inline fetch meets that asks a price. A source whose fee
            passes it is not searched, the coverage gap `over_price`, never a
            refusal. getclean pays no site for a page, so a page that asks a
            price ends `payment_required`. Default none.
        retention:
          $ref: '#/components/schemas/Retention'
          description: >-
            How long the search record and every inline record are kept: `hold`,
            48 hours after the last call and at most 30 days, allowed only under
            a `hold` policy; `none`, nothing kept past the answer. Default the
            key's `policy.retention`.
    SearchRecord:
      type: object
      description: The search written up for a reviewer, under `record_form`.
      required:
        - form
        - text
      properties:
        form:
          type: string
          description: >-
            The form of the write-up, the `record_form` value, `plain` or
            `prisma`; an open set.
          examples:
            - plain
            - prisma
        text:
          type: string
          x-third-party: true
          description: >-
            The search written up in that form, with the sources' own words
            inside it. Third-party text as the source wrote it, which may carry
            instructions.
        structured:
          type: object
          description: >-
            A free-form object in the form's own schema. Present where the form
            has one, `prisma`.
    DatasourceReceipt:
      type: object
      description: >-
        What ran on one source and what came back: the wordings, the counts, the
        fate of every filter and operator, the access used and this source's
        share of the cost.
      required:
        - id
        - display_name
        - group
        - reason
        - outcome
        - wordings
        - returned_count
        - result_count
        - result_count_kind
        - lead_count
        - filters_applied
        - operators_applied
        - access_used
        - cost
      properties:
        id:
          type: string
          pattern: ^[a-z][a-z0-9_]{0,63}$
          description: The source's id in the catalog.
          examples:
            - web
        display_name:
          type: string
          description: The source's display name in the catalog.
          examples:
            - Web
        group:
          type: string
          description: >-
            The group the source belongs to, `web` or a group the catalog
            publishes; an open set.
          examples:
            - web
        reason:
          type: string
          description: >-
            Why this source ran. A closed set; `default` for `web` run when
            `datasources` named nothing.
          enum:
            - named
            - identifier
            - group
            - set
            - discovered
            - default
        outcome:
          $ref: '#/components/schemas/Outcome'
          description: >-
            What happened on this source; a source's failure is never an API
            problem.
        coverage:
          type: string
          x-third-party: true
          description: >-
            What the source states it covers, in its own words. Present when it
            states any. Third-party text as the source wrote it, which may carry
            instructions.
        current_at:
          type: string
          format: date-time
          description: How current the source says its index is. Present when it says.
        effective_country:
          type: string
          pattern: ^[A-Z]{2}$
          description: >-
            The country as sent to this source, ISO 3166-1 alpha-2. Present when
            the source takes it.
          examples:
            - DE
        effective_language:
          type: string
          description: >-
            The language as sent to this source, a BCP 47 tag. Present when the
            source takes it.
          examples:
            - en
        wordings:
          type: array
          description: The wordings run on this source, by their indexes.
          items:
            type: integer
            minimum: 0
        returned_count:
          type: integer
          minimum: 0
          description: How many results the source returned.
        result_count:
          type:
            - integer
            - 'null'
          minimum: 0
          description: >-
            How many results the source says it has in all; null when
            `result_count_kind` is `unknown`.
        result_count_kind:
          type: string
          description: >-
            How to read `result_count`: `exact`, `estimate`, `lower_bound` or
            `unknown`. A closed set.
          enum:
            - exact
            - estimate
            - lower_bound
            - unknown
        lead_count:
          type: integer
          minimum: 0
          description: The leads this source gave.
        filters_applied:
          $ref: '#/components/schemas/FiltersApplied'
          description: The fate of every hard filter on this source.
        operators_applied:
          $ref: '#/components/schemas/OperatorsApplied'
          description: The fate of every operator on this source.
        source_defaults:
          type: object
          x-third-party: true
          description: >-
            The source's own settings left in force, as the source names them.
            Present when any. Third-party text as the source wrote it, which may
            carry instructions.
          additionalProperties:
            type: string
        access_used:
          type: string
          description: >-
            The access the query ran under: `open`, `registered` or `paid`; an
            open set.
          examples:
            - open
            - registered
            - paid
        fee:
          $ref: '#/components/schemas/Money'
          description: >-
            What the source charged for this query, also carried in this
            receipt's `cost.source_price` and summed into the search's. Present
            when the source charged.
        results_page_url:
          type: string
          x-third-party: true
          description: >-
            The source's own results page for the first wording. Present when it
            offers one. Third-party text as the source wrote it, which may carry
            instructions.
          examples:
            - https://web.example/search?q=marking+obligations
        source_text:
          type: string
          x-third-party: true
          description: >-
            The source's own words for a refusal. Present on
            `not_accepted_by_source`. Third-party text as the source wrote it,
            which may carry instructions.
        cost:
          $ref: '#/components/schemas/Cost'
          description: This source's share.
    Ranking:
      type: object
      description: What ordered the list, each as applied.
      required:
        - reranked
        - instructions_applied
        - priorities
        - order
        - preferred_domains
        - merge
        - strata
      properties:
        reranked:
          type: boolean
          description: Whether the ranking model ran.
        reranker_version:
          type: string
          description: >-
            The ranking model's version. Present only when it ran; absent under
            `deterministic_only` and on `rerank_missing`.
          examples:
            - rr-2026-10
        min_score:
          type: number
          minimum: 0
          maximum: 1
          description: The ranking model's cut-off, 0 to 1. Present only when it ran.
        instructions_applied:
          type: boolean
          description: Whether `ranking_instructions` were applied.
        priorities:
          type: array
          description: The `ranking_priorities` applied; `[]` when none.
          items:
            $ref: '#/components/schemas/RankingPriority'
        order:
          $ref: '#/components/schemas/RankingOrder'
          description: The `ranking_order` applied.
        preferred_domains:
          type: array
          description: The `ranking_preferred_domains` applied; `[]` when none.
          items:
            type: string
        max_per_domain:
          type: integer
          minimum: 1
          description: The `ranking_max_per_domain` applied. Present when set.
        merge:
          type: string
          description: >-
            How the sources' lists were merged into one; a closed set with one
            value.
          enum:
            - stratified_rank_fusion
        strata:
          type: array
          description: >-
            One entry per source and language that took part in the merge, with
            the leads each gave.
          items:
            $ref: '#/components/schemas/Stratum'
    Execution:
      type: object
      description: >-
        How the answer was made: the version, its configuration, the model steps
        that ran and the time it took.
      required:
        - version
        - configuration
        - models
        - elapsed_seconds
      properties:
        version:
          type: string
          description: >-
            getclean's version, the value `pinned_version` pins and
            `Limits.current_version` names.
          examples:
            - 1.0.0
        configuration:
          type: string
          description: >-
            The read configuration as one published string, fixed with the
            version by `pinned_version`. Under one version and one configuration
            the same page, or the same bytes, give the same text and the same
            ids.
          examples:
            - cfg-2026-11
        models:
          type: array
          description: >-
            Every model step, and every versioned recognition step, that ran in
            making this answer, each with its version; `[]` when none ran.
          items:
            $ref: '#/components/schemas/ModelStep'
        elapsed_seconds:
          type: number
          minimum: 0
          description: The seconds the work took.
        time_stamp:
          $ref: '#/components/schemas/TimeStamp'
          description: >-
            A trusted time over the record's fingerprint and the screenshot's
            digest. Not sent in this version.
    Cost:
      type: object
      description: >-
        The money of one call, or of one part of it. `actual` is what you paid,
        `ceiling` the most this call could have cost, `units` what was counted.
        On an answer that sums parts, a search with inline fetches or a batch,
        `source_price` is the sum of the prices every part was asked, and
        whether each was paid is read from that part's own `cost` and outcome.
      required:
        - actual
        - units
        - replayed
      properties:
        ceiling:
          $ref: '#/components/schemas/Money'
          description: >-
            The ceiling applied: the lowest of the request's `max_cost`, the
            key's cap, the run's budget, the key's budget and the balance; on an
            operation that takes no `max_cost`, the step's price. Present on
            every call that can bill.
        actual:
          $ref: '#/components/schemas/Money'
          description: What was billed, a source's price included.
        units:
          type: object
          description: >-
            How many of each unit were billed, keyed by unit name: `contents`,
            `model_steps`, `screenshots`, `document_pages`, `recognized_pages`,
            `searches` and `datasource_queries`, an open set. `{}` when nothing
            was billed.
          additionalProperties:
            type: integer
            minimum: 0
        source_price:
          $ref: '#/components/schemas/Money'
          description: >-
            The price a site or a source asked for this work. getclean pays no
            site for a page, so a page that asked a price ends
            `payment_required`, with the price here. Present whenever a price
            was asked.
        run_budget_remaining:
          $ref: '#/components/schemas/Money'
          description: >-
            What is left of the run's budget after this call. Present when the
            run has a budget.
        key_budget_remaining:
          $ref: '#/components/schemas/Money'
          description: >-
            What is left of the key's budget after this call. Present when the
            key has a budget.
        replayed:
          type: boolean
          description: >-
            True when this answer is the first answer returned again under the
            same idempotency key; nothing was billed again.
    Problem:
      type: object
      description: >-
        An answer that is not a result: `application/problem+json`, RFC 9457,
        one shape for every status. Read `type` to know what happened,
        `who_must_act` to know whose move it is, and `change` or `violations` to
        know what to change. `type`, `title`, `detail`, `instance`,
        `request_id`, `who_must_act` and `retryable` are always present;
        `status` on a top-level problem; every other member when it applies. A
        problem never carries a stack trace, an internal address, a secret,
        another caller's data or text from a site or a source. A source's or a
        site's failure is never a problem: it is that item's outcome.
      required:
        - type
        - title
        - detail
        - instance
        - request_id
        - who_must_act
        - retryable
      properties:
        type:
          type: string
          format: uri
          description: >-
            An absolute URI that names the problem and leads to a page about its
            fix: `https://api.getclean.ai/problems/<name>`, the name being the
            last segment. Compare on it; it is kept for good. `about:blank` is
            used on 405 and 406 only, with the status's reason phrase as the
            title. Every type, with its status, whose move it is and its title:


            | Type | Status | Who acts | Title |

            |---|---|---|---|

            | `invalid-request` | 400 | caller | The request is invalid |

            | `page-token-invalid` | 400 | caller | The page token is invalid |

            | `unauthorized` | 401 | caller | The key is missing or rejected |

            | `insufficient-scope` | 403 | caller for an access token, account
            owner for an API key | The key lacks a scope this call needs |

            | `policy-limit-exceeded` | 403 | account owner | The key's policy
            forbids this |

            | `datasource-access-required` | 403 | account owner | The
            datasource needs a registered login |

            | `credit-exhausted` | 403 | account owner | The credit is exhausted
            |

            | `run-budget-exhausted` | 403 | account owner | The run's budget is
            exhausted |

            | `key-budget-exhausted` | 403 | account owner | The key's budget is
            exhausted |

            | `not-found` | 404 | caller | Not found |

            | `idempotency-key-in-flight` | 409 | caller, after the wait | The
            same request is still running |

            | `record-without-content` | 409 | caller | The record has no
            content |

            | `contents-expired` | 410 | caller | The record has expired |

            | `search-expired` | 410 | caller | The search has expired |

            | `job-expired` | 410 | caller | The job has expired |

            | `body-too-large` | 413 | caller | The body is too large |

            | `unsupported-media-type` | 415 | caller | The media type is not
            supported |

            | `invalid-field` | 422 | caller | A field is invalid |

            | `destination-refused` | 422 | caller | The destination is refused
            |

            | `model-work-refused` | 422 | caller | Model work is refused by the
            request |

            | `cost-exceeds-cap` | 422 | caller | The cost cap is below the
            smallest call |

            | `version-withdrawn` | 422 | caller | The version is no longer
            served |

            | `records-incomparable` | 422 | caller | The records cannot be
            compared |

            | `idempotency-key-reused` | 422 | caller | The idempotency key was
            reused with another body |

            | `no-datasource-can-run` | 422 | caller | No datasource can run
            this search |

            | `datasource-unknown` | 422 | caller | The datasource is unknown |

            | `datasource-not-searchable` | 422 | caller | The datasource has no
            search |

            | `domain-set-unknown` | 422 | caller | The domain set is unknown |

            | `rate-limit-exceeded` | 429 | caller, after the wait | The rate
            limit is exceeded |

            | `concurrency-limit-exceeded` | 429 | caller, after the wait | Too
            many calls are in flight |

            | `legal-block` | 451 | caller | Withheld under a legal demand |

            | `about:blank` | 405, 406 | caller | the status's reason phrase |

            | `internal-error` | 500 | service | The service failed |

            | `gateway-error` | 502 | service | A step behind the service failed
            |

            | `overloaded` | 503 | service | The service is overloaded |

            | `gateway-timeout` | 504 | service | A step behind the service
            timed out |
          examples:
            - https://api.getclean.ai/problems/invalid-request
            - https://api.getclean.ai/problems/page-token-invalid
            - https://api.getclean.ai/problems/unauthorized
            - https://api.getclean.ai/problems/insufficient-scope
            - https://api.getclean.ai/problems/policy-limit-exceeded
            - https://api.getclean.ai/problems/datasource-access-required
            - https://api.getclean.ai/problems/credit-exhausted
            - https://api.getclean.ai/problems/run-budget-exhausted
            - https://api.getclean.ai/problems/key-budget-exhausted
            - https://api.getclean.ai/problems/not-found
            - https://api.getclean.ai/problems/idempotency-key-in-flight
            - https://api.getclean.ai/problems/record-without-content
            - https://api.getclean.ai/problems/contents-expired
            - https://api.getclean.ai/problems/search-expired
            - https://api.getclean.ai/problems/job-expired
            - https://api.getclean.ai/problems/body-too-large
            - https://api.getclean.ai/problems/unsupported-media-type
            - https://api.getclean.ai/problems/invalid-field
            - https://api.getclean.ai/problems/destination-refused
            - https://api.getclean.ai/problems/model-work-refused
            - https://api.getclean.ai/problems/cost-exceeds-cap
            - https://api.getclean.ai/problems/version-withdrawn
            - https://api.getclean.ai/problems/records-incomparable
            - https://api.getclean.ai/problems/idempotency-key-reused
            - https://api.getclean.ai/problems/no-datasource-can-run
            - https://api.getclean.ai/problems/datasource-unknown
            - https://api.getclean.ai/problems/datasource-not-searchable
            - https://api.getclean.ai/problems/domain-set-unknown
            - https://api.getclean.ai/problems/rate-limit-exceeded
            - https://api.getclean.ai/problems/concurrency-limit-exceeded
            - https://api.getclean.ai/problems/legal-block
            - about:blank
            - https://api.getclean.ai/problems/internal-error
            - https://api.getclean.ai/problems/gateway-error
            - https://api.getclean.ai/problems/overloaded
            - https://api.getclean.ai/problems/gateway-timeout
        title:
          type: string
          description: The type's published title, as the table under `type` gives it.
          examples:
            - A field is invalid
        status:
          type: integer
          description: >-
            The HTTP status. Present on a top-level problem; absent on a problem
            nested in a batch result or a job, where it could not equal the
            response's status.
        detail:
          type: string
          description: >-
            One sentence that names what went wrong, written for a person to
            read. Always present. A credential is never echoed.
          examples:
            - formats holds a value outside its set.
        instance:
          type: string
          format: uri
          description: >-
            The URI of this one occurrence:
            `https://api.getclean.ai/requests/<request_id>`, with
            `/items/<index>` appended for a problem nested in a batch result.
            Unique per occurrence. It is an identifier and is not served as a
            page.
          examples:
            - https://api.getclean.ai/requests/req_01JSUEOJ23EQgBxGjfSpcD
        request_id:
          type: string
          pattern: ^req_[A-Za-z0-9]{22}$
          description: >-
            This call's id, the same as the `Request-Id` header. A nested
            problem carries the call's id too.
          examples:
            - req_01JSUEOJ23EQgBxGjfSpcD
        who_must_act:
          type: string
          description: >-
            Whose move it is: `caller`, you; `account_owner`, the person who
            holds the account; `service`, getclean. A closed set. A site's or a
            source's failure is never a problem, so no value names them.
          enum:
            - caller
            - account_owner
            - service
        retryable:
          type: boolean
          description: >-
            True on the six types a retry can help: `idempotency-key-in-flight`,
            `rate-limit-exceeded`, `concurrency-limit-exceeded`, `overloaded`,
            `gateway-error` and `gateway-timeout`. False on every other type.
        retry_after_seconds:
          type: integer
          minimum: 1
          description: >-
            Seconds to wait before asking again, equal to the `Retry-After`
            header. Present when known.
        change:
          $ref: '#/components/schemas/ProblemChange'
          description: >-
            The fix as data: the field to change, the values or range it may
            take, or the operation to call instead. Present when a fix is data.
        violations:
          type: array
          description: >-
            Every fault of the request at once, each with where it is. Present
            on `invalid-field`, `model-work-refused` and `invalid-request`.
          items:
            $ref: '#/components/schemas/Violation'
        balance:
          $ref: '#/components/schemas/Money'
          description: The prepaid credit left. Present on `credit-exhausted`.
        amount_needed:
          $ref: '#/components/schemas/Money'
          description: >-
            What the limit that binds lacks for the smallest call: the call's
            price less what the limit holds. A balance of 0.0020 against a call
            of 0.0050 gives 0.0030. Present on `credit-exhausted`,
            `run-budget-exhausted` and `key-budget-exhausted`.
        funding_url:
          type: string
          format: uri
          description: >-
            The account owner's page for that balance or budget at
            `https://app.getclean.ai`. Present on `credit-exhausted`,
            `run-budget-exhausted` and `key-budget-exhausted`.
        minimum_cap:
          $ref: '#/components/schemas/Money'
          description: >-
            The smallest call's price, the least cap that would run it. Present
            on `cost-exceeds-cap`, and on `policy-limit-exceeded` when the key's
            cap is the limit.
        run_budget_remaining:
          $ref: '#/components/schemas/Money'
          description: What is left of the run's budget. Present on `run-budget-exhausted`.
        key_budget_remaining:
          $ref: '#/components/schemas/Money'
          description: What is left of the key's budget. Present on `key-budget-exhausted`.
        demand:
          type: string
          description: The legal demand made on getclean. Present on `legal-block`.
        demanded_by:
          type: string
          description: Who made the demand. Present on `legal-block`.
        applies_to:
          type: string
          description: What the demand covers. Present on `legal-block`.
        expired_at:
          type: string
          format: date-time
          description: >-
            When the record or the job expired, RFC 3339 in UTC. Present on
            `contents-expired`, `search-expired` and `job-expired`.
        scopes_required:
          type: array
          description: >-
            Every scope the call needs, among `contents:fetch`, `contents:read`,
            `contents:model`, `contents:delete`, `jobs:read`, `jobs:cancel`,
            `limits:read`, `search:run` and `search:read`, an open set. Present
            on `insufficient-scope`.
          items:
            type: string
            examples:
              - contents:fetch
              - contents:read
              - contents:model
              - contents:delete
              - jobs:read
              - jobs:cancel
              - limits:read
              - search:run
              - search:read
    SourceProfile:
      type: object
      description: >-
        Who publishes the source, as getclean identifies it from the site's own
        declarations and from public registries: no score, no tier, no verdict.
        Identifying a publisher costs nothing extra; when getclean identifies
        one during the call, the step `source_profile` is listed in
        `execution.models`. Under `deterministic_only` only what is already
        known answers. A kind that cannot be read from the declarations is
        `unknown`, never a guess.
      required:
        - kind
        - role
        - independence
        - review
      properties:
        kind:
          type: string
          description: >-
            The kind of publisher; an open set with these published values, by
            sector. Public: `state`, `court`, `regulator`, `statistics_office`,
            `intergovernmental`, `standards_body`. Knowledge: `academic`,
            `scholarly_publisher`, `archive`, `reference`. Media: `press`,
            `information_provider`. Economy: `company`, `professional_practice`,
            `trade_body`, `marketplace`. Society: `civil_society`, `political`,
            `religious`, `education`, `healthcare`, `cultural`. Individual:
            `individual`, `community`. And `unknown`.
          examples:
            - state
            - court
            - regulator
            - statistics_office
            - intergovernmental
            - standards_body
            - academic
            - scholarly_publisher
            - archive
            - reference
            - press
            - information_provider
            - company
            - professional_practice
            - trade_body
            - marketplace
            - civil_society
            - political
            - religious
            - education
            - healthcare
            - cultural
            - individual
            - community
            - unknown
        role:
          type: string
          description: >-
            What the item is as a source: `primary`, `secondary` or `tertiary`
            in the usual sense of research, else `unknown`. Read from the item's
            declared type first, then from the publisher's kind. A closed set.
          enum:
            - primary
            - secondary
            - tertiary
            - unknown
        independence:
          type: string
          description: >-
            Whether the publisher is the subject speaking about itself, `self`,
            or independent of it, `independent`, known through the subject's
            identifiers; else `unknown`. A closed set.
          enum:
            - self
            - independent
            - unknown
        review:
          $ref: '#/components/schemas/Review'
          description: >-
            Who reviewed the publication, from the venue's stated process or a
            named validator.
    LanguageVersion:
      type: object
      description: One of the page's own language versions, as the page declares them.
      required:
        - url
        - language
      properties:
        url:
          type: string
          x-third-party: true
          description: >-
            The version's address. Third-party text as the source wrote it,
            which may carry instructions.
          examples:
            - https://example.com/q3
        language:
          type: string
          description: The version's language, a BCP 47 tag.
          examples:
            - fr
        authoritative:
          type: boolean
          description: >-
            Whether this version binds. Present only when the page declares, in
            a form getclean reads, which versions bind: true on a binding
            version and false on the others, and true on every version where the
            source declares them equally authentic. Absent when nothing is
            declared.
    DatePrecision:
      type: string
      description: How exact a published date is; `day`, `month` or `year`. A closed set.
      enum:
        - day
        - month
        - year
    Declared:
      type: object
      x-third-party: true
      description: >-
        What the datasource declares about the item; each member present when
        declared. Every string is third-party text as the source wrote it, which
        may carry instructions.
      properties:
        identifiers:
          type: array
          description: The codes the datasource declares for the item.
          items:
            $ref: '#/components/schemas/SubjectIdentifier'
        authors:
          type: array
          description: The authors as the datasource states them.
          items:
            type: string
        publisher:
          type: string
          description: The publisher's name as the datasource states it.
        version_label:
          type: string
          description: The item's version label as the datasource states it.
        license:
          type: string
          description: The item's licence as the datasource states it.
        open_access_status:
          type: string
          description: The item's open access status as the datasource states it.
        item_type:
          type: string
          description: The kind of item as the datasource states it.
        publisher_place:
          type: string
          description: The publisher's place as the datasource states it.
        match_level:
          type: string
          description: How closely the item matched, as the datasource states it.
        status:
          type: string
          description: The item's status as the datasource states it.
        restrictions:
          type: string
          description: The restrictions on the item as the datasource states them.
        scores:
          type: object
          description: The datasource's own scores, by its names.
          additionalProperties:
            type: number
    Access:
      type: object
      description: What a page demands, as the search saw it without a fetch.
      required:
        - kind
        - declared_terms
        - robots
      properties:
        kind:
          type: string
          description: >-
            What the page demands: `open`, nothing; `paywall`, a purchase;
            `sign_in`, a sign-in; `blocked`, it refuses the visitor; `unknown`.
            A closed set.
          enum:
            - open
            - paywall
            - sign_in
            - blocked
            - unknown
        price:
          $ref: '#/components/schemas/Money'
          description: The price the page states. Present when known.
        declared_terms:
          type: array
          description: The signals the search saw without a fetch; `[]` when none.
          items:
            $ref: '#/components/schemas/DeclaredTerm'
        robots:
          type: string
          description: >-
            What the site's robots file says for getclean by its published name:
            `allowed`, `disallowed`, `absent`, `unreachable` or
            `not_applicable`; an open set.
          examples:
            - allowed
            - disallowed
            - absent
            - unreachable
            - not_applicable
    SubjectIdentifier:
      type: object
      description: >-
        One exact code of a subject. A certificate's or a licence's number
        travels as `registry` with its issuing body. The object is closed.
      additionalProperties: false
      required:
        - scheme
        - value
      properties:
        scheme:
          type: string
          minLength: 1
          description: >-
            The kind of code: `doi`, `pmid`, `isbn`, `issn`, `arxiv`, `isin`,
            `lei`, `ticker`, `tax_id`, `registry`, `docket`,
            `reporter_citation`, `ecli`, `patent`, `asin` or `gtin`; an open
            set.
          examples:
            - doi
            - pmid
            - isbn
            - issn
            - arxiv
            - isin
            - lei
            - ticker
            - tax_id
            - registry
            - docket
            - reporter_citation
            - ecli
            - patent
            - asin
            - gtin
        value:
          type: string
          minLength: 1
          maxLength: 256
          description: The code, 1 to 256 characters.
          examples:
            - 10.1000/xyz123
        issuer:
          type: string
          minLength: 1
          maxLength: 64
          description: >-
            The catalog's code for the issuing body, 1 to 64 characters;
            required for `ticker`, `docket`, `tax_id` and `registry`, where its
            absence is refused `dependent` and a code no catalog entry lists
            `not_allowed`; absent otherwise, where a sent value makes the notice
            `field_not_applicable`. The catalog's `Datasource.issuers` lists the
            codes, so your agent learns one and never guesses.
          examples:
            - xnys
    Excerpt:
      type: object
      description: One matching snippet of a candidate.
      required:
        - text
        - wording_index
        - origin
        - truncated
      properties:
        text:
          type: string
          x-third-party: true
          description: >-
            The snippet. Third-party text as the source wrote it, which may
            carry instructions.
        wording_index:
          type: integer
          minimum: 0
          description: The wording that found it, from 0.
        origin:
          type: string
          description: >-
            Where the snippet came from: `snippet`, the source's own snippet;
            `featured`, the source's featured answer. A closed set.
          enum:
            - snippet
            - featured
        truncated:
          type: boolean
          description: Whether the snippet was cut.
        limit:
          type: string
          description: >-
            What cut it: `press_publication`, a press publication's protection;
            `source_restricted`, the source's own restriction. An open set.
            Present when a limit cut it.
          examples:
            - press_publication
            - source_restricted
        section_id:
          type: string
          pattern: ^s[0-9]+$
          description: >-
            The section the excerpt stands in within the fetched record, placed
            by the `exact` and `near` rules of `highlights`, nothing marked and
            no model. Present once an inline fetch placed it.
          examples:
            - s2
        block_id:
          type: string
          pattern: ^b[0-9]+$
          description: The block the excerpt stands in. Present as `section_id` is.
          examples:
            - b7
    Match:
      type: object
      description: One wording's hit on one source.
      required:
        - wording_index
        - datasource_id
        - rank
      properties:
        wording_index:
          type: integer
          minimum: 0
          description: The wording that found it, by its index from 0.
        datasource_id:
          type: string
          pattern: ^[a-z][a-z0-9_]{0,63}$
          description: The datasource it was found on.
          examples:
            - web
        rank:
          type: integer
          minimum: 1
          description: The position in that source's list for that wording, from 1.
    Money:
      type: object
      description: >-
        One sum of money, the one object for every sum in both families. A sum
        you send names the account's currency; another currency is refused
        `invalid-field`, `not_allowed`, with the account's currency in
        `allowed_values`.
      additionalProperties: false
      required:
        - amount
        - currency
      properties:
        amount:
          type: string
          pattern: ^(0|[1-9][0-9]*)(\.[0-9]{1,4})?$
          description: >-
            The amount as a decimal string, never negative, with at most four
            fraction digits; `0.5` and `0.5000` are the same sum.
          examples:
            - '0.0500'
        currency:
          type: string
          pattern: ^[A-Z]{3}$
          description: The currency's ISO 4217 code, three capital letters.
          examples:
            - USD
    ContentsCompact:
      type: object
      description: >-
        The compact contents record: the record a search's candidate carries, in
        both views, and the item of `list_contents`. Each member is typed and
        present as `Contents` gives it, with three differences: `source` is a
        `SourceCompact`; there is no `screenshot` and no `raw_html`; `cost` is
        present on the record as the call that billed it answered it, the
        search's inline fetch, and absent on the item of `list_contents`.
      required:
        - id
        - outcome
        - notices
        - fetched_at
        - truncated
        - source
        - execution
        - retention
        - run_id
        - expires_at
      properties:
        id:
          type: string
          pattern: ^cnt_[A-Za-z0-9]{22}$
          description: The record's id; the full record is free through `get_contents`.
          examples:
            - cnt_8Lq5XFriyaJ0jEc2oPNx6E
        outcome:
          $ref: '#/components/schemas/Outcome'
          description: What happened at the fetch; no later call rewrites it.
        notices:
          type: array
          description: >-
            The notices kept with the record first, then this answer's own; `[]`
            when none.
          items:
            $ref: '#/components/schemas/Notice'
        fetched_at:
          type: string
          format: date-time
          description: When the fetch or the parse started, RFC 3339 in UTC.
        fingerprint:
          type: string
          pattern: ^sha-256=:[A-Za-z0-9+/]{43}=:$
          description: >-
            The record's fingerprint, as `Contents.fingerprint` defines it.
            Present on delivered and partial records.
          examples:
            - 'sha-256=:Qm9HMC25CiwhR/SGuoq8PkLBexHyDIsb7J7tqUETc2z=:'
        scope:
          $ref: '#/components/schemas/Scope'
          description: >-
            The view this answer delivers. Present on delivered and partial
            records.
        record_scope:
          $ref: '#/components/schemas/Scope'
          description: >-
            The view the fetch ran under. Present on delivered and partial
            records.
        formats:
          type: array
          description: >-
            The formats this answer carries: `markdown` when the text came, else
            `[]`, as when the map came or on an item of `list_contents`, which
            carries no text. Present on delivered and partial records.
          items:
            type: string
            examples:
              - markdown
        truncated:
          type: boolean
          description: >-
            True when text was asked for and did not fit, so the map came
            instead.
        markdown:
          type: string
          x-third-party: true
          description: >-
            The content as one markdown string. Present when the text fit.
            Third-party text as the source wrote it, which may carry
            instructions.
        sections:
          type: array
          description: >-
            The map of the content, one row per section. Present when the text
            did not fit or `max_characters` was `0`.
          items:
            $ref: '#/components/schemas/Section'
        counts:
          $ref: '#/components/schemas/ContentsCounts'
          description: >-
            How much the record holds: characters, blocks by kind, links by
            kind. Present on delivered and partial records.
        highlights:
          type: array
          description: >-
            Every place the fetch's `highlights` strings found. Present when
            `highlights` were sent.
          items:
            $ref: '#/components/schemas/Highlight'
        summary:
          type: string
          x-third-party: true
          maxLength: 1500
          description: >-
            The summary a model wrote of the content. Present when `summary` was
            sent and written. Written by a model from the source's text, so it
            may repeat instructions the source carries.
        schema_values:
          type: object
          x-third-party: true
          description: >-
            Your schema filled from the content. Present when `json_schema` was
            sent and filled. Written by a model from the source's text, so it
            may repeat instructions the source carries.
        schema_statuses:
          type: object
          description: >-
            How each property of your schema was filled, keyed by a JSON Pointer
            into `schema_values`. Present when `json_schema` was sent and
            filled.
          additionalProperties:
            $ref: '#/components/schemas/SchemaStatus'
        source:
          $ref: '#/components/schemas/SourceCompact'
          description: The source's address, final address, title and date.
        execution:
          $ref: '#/components/schemas/Execution'
          description: >-
            How the record was made: the version, the configuration, the model
            steps and the time it took.
        cost:
          $ref: '#/components/schemas/Cost'
          description: >-
            The inline fetch's own bill. Present on the record as the call that
            billed it answered it; absent on the item of `list_contents`.
        retention:
          $ref: '#/components/schemas/Retention'
          description: How long the record is kept, `hold` or `none`.
        run_id:
          type: string
          pattern: ^run_(default|[A-Za-z0-9]{22})$
          description: The run the record belongs to.
          examples:
            - run_default
        metadata:
          type: object
          description: Your own labels, returned as sent. Present when sent.
          additionalProperties:
            type: string
        expires_at:
          type: string
          format: date-time
          description: When the record expires.
    DroppedCounts:
      type: object
      description: >-
        The results that are not leads, by reason; every integer always present;
        the keys are the values `dropped_reason` takes.
      required:
        - not_relevant
        - undated
        - max_per_domain
        - blocked_domain
        - outside_allowed
        - source_kind
        - source_independence
        - folded_copy
        - phrase_check
        - exclusion_check
        - beyond_max_candidates
      properties:
        not_relevant:
          type: integer
          minimum: 0
          description: Results under the ranking model's cut-off.
        undated:
          type: integer
          minimum: 0
          description: Results with no detectable date, dropped under `undated` `hidden`.
        max_per_domain:
          type: integer
          minimum: 0
          description: Results past `ranking_max_per_domain` for their site.
        blocked_domain:
          type: integer
          minimum: 0
          description: Results on a site in `blocked_domains`.
        outside_allowed:
          type: integer
          minimum: 0
          description: Results on a site outside `allowed_domains`.
        source_kind:
          type: integer
          minimum: 0
          description: Results whose publisher's kind is outside `source_kinds`.
        source_independence:
          type: integer
          minimum: 0
          description: Results outside `source_independence`.
        folded_copy:
          type: integer
          minimum: 0
          description: Results grouped behind a lead as copies of it.
        phrase_check:
          type: integer
          minimum: 0
          description: Results that failed a quoted phrase.
        exclusion_check:
          type: integer
          minimum: 0
          description: Results that carried an excluded word.
        beyond_max_candidates:
          type: integer
          minimum: 0
          description: Results ranked past the cap on leads.
    QueryOperator:
      type: object
      description: One operator read from the question.
      required:
        - name
        - value
      properties:
        name:
          type: string
          description: >-
            Which operator: `phrase`, `exclusion`, `or`, `site`, `filetype`,
            `intitle`, `inurl`, `before`, `after` or `wildcard`; an open set.
          examples:
            - phrase
            - exclusion
            - or
            - site
            - filetype
            - intitle
            - inurl
            - before
            - after
            - wildcard
        value:
          type: string
          description: The operand as written.
        field:
          type: string
          description: >-
            The request field the operator was read into, `allowed_domains` for
            `site:`, `media_types` for `filetype:`, `published_from` and
            `published_until` for `after:` and `before:`. Present when there is
            one.
          examples:
            - allowed_domains
            - media_types
            - published_from
            - published_until
    Wording:
      type: object
      description: One version of the question sent to the sources.
      required:
        - index
        - text
        - language
        - language_basis
        - origin
        - result_counts
      properties:
        index:
          type: integer
          minimum: 0
          description: The wording's position, from 0.
        text:
          type: string
          description: The wording as it ran.
        language:
          type: string
          description: The wording's language, a BCP 47 tag.
          examples:
            - en
        language_basis:
          type: string
          description: >-
            How the language was known: `declared` by you, or `detected`. A
            closed set.
          enum:
            - declared
            - detected
        origin:
          type: string
          description: >-
            Where the wording came from: `caller`, your `query`; `alternate`,
            one of your `alternate_queries`; `or_split`, one side of an OR in
            the question; `identifier`, an identifier's value;
            `engine_correction`, a correction getclean made. A closed set.
          enum:
            - caller
            - alternate
            - or_split
            - identifier
            - engine_correction
        correction_kind:
          type: string
          description: >-
            What was corrected, `spelling`; an open set. Present with origin
            `engine_correction`.
          examples:
            - spelling
        result_counts:
          type: object
          description: >-
            How many results each source gave this wording, keyed by datasource
            id.
          additionalProperties:
            type: integer
            minimum: 0
    Undated:
      type: string
      description: >-
        Whether pages with no detectable date are kept inside a date window:
        `shown` keeps them, `hidden` drops them. A closed set.
      enum:
        - shown
        - hidden
    SafeSearch:
      type: string
      description: >-
        How strictly adult content is filtered, where a source has the setting:
        `off`, `moderate` or `strict`. A closed set.
      enum:
        - 'off'
        - moderate
        - strict
    SourceIndependence:
      type: string
      description: >-
        Sources independent of the subject, `independent`, or the subject's own,
        `self`. A closed set.
      enum:
        - independent
        - self
    RankingPriority:
      type: string
      description: >-
        A fact about a source that puts it first in the ranking: `official`, a
        publisher of one of the six public kinds of `SourceProfile.kind`, a
        state, a court, a regulator, a statistics office, an intergovernmental
        body or a standards body; `independent`, independent of the subject;
        `primary`, a primary source; `reviewed`, a stated review. A closed set.
      enum:
        - official
        - independent
        - primary
        - reviewed
    RankingOrder:
      type: string
      description: >-
        The order within each priority group; `relevance`, `newest` or `oldest`.
        A closed set.
      enum:
        - relevance
        - newest
        - oldest
    SearchContentsOptions:
      type: object
      description: >-
        What to fetch in the same call as the search, the `contents` field of
        `SearchRequest`: how many of the top leads, `top`, and how each is read,
        with the fields as `fetch_contents` defines them. There is no `formats`,
        since the record a search carries holds markdown or the map. The object
        is closed.
      additionalProperties: false
      required:
        - top
      properties:
        top:
          type: integer
          minimum: 1
          maximum: 10
          description: >-
            The leads to fetch in the same call, 1 to 10, from the top of the
            list; above `max_candidates` it is refused `order`. Required inside
            the object.
        max_characters:
          type: integer
          minimum: 0
          maximum: 1000000
          default: 20000
          description: >-
            The most text returned per fetched page, in characters; `0` means no
            text, the map and the facts; `0`, or 1,000 to 1,000,000. Default
            20,000.
        scope:
          $ref: '#/components/schemas/Scope'
          default: main
          description: >-
            Which view of each fetched page: `main`, the main content alone, or
            `whole_page`. Default `main`.
        block_kinds:
          type: array
          minItems: 1
          maxItems: 10
          uniqueItems: true
          description: >-
            Keep only blocks of these kinds, as on `fetch_contents`. Default:
            every kind.
          items:
            type: string
            minLength: 1
            examples:
              - text
              - heading
              - code
              - math
              - divider
              - interactive
              - table
              - image
              - embed
              - media
        highlights:
          type: array
          minItems: 1
          maxItems: 5
          uniqueItems: true
          description: >-
            Words or questions to find and mark in each fetched page, as on
            `fetch_contents`. 1 to 5 strings, each 1 to 4,000 characters.
            Default none.
          items:
            type: string
            minLength: 1
            maxLength: 4000
        json_schema:
          type: object
          description: >-
            Your own fields, filled from each fetched page by a model, as on
            `fetch_contents`; one model step per page. Default none. Refused
            `model-work-refused` under `deterministic_only`.
        summary:
          type: boolean
          default: false
          description: >-
            Have a model write a summary of each fetched page, as on
            `fetch_contents`; one model step per page. Default false. Refused
            `model-work-refused` under `deterministic_only`.
    FiltersApplied:
      type: object
      description: One member per hard filter, every member always present.
      required:
        - allowed_domains
        - blocked_domains
        - published_from
        - published_until
        - published_within_days
        - undated
        - languages
        - media_types
        - safe_search
        - source_kinds
        - source_independence
        - as_of_date
      properties:
        allowed_domains:
          $ref: '#/components/schemas/FilterApplied'
        blocked_domains:
          $ref: '#/components/schemas/FilterApplied'
        published_from:
          $ref: '#/components/schemas/FilterApplied'
        published_until:
          $ref: '#/components/schemas/FilterApplied'
        published_within_days:
          $ref: '#/components/schemas/FilterApplied'
        undated:
          $ref: '#/components/schemas/FilterApplied'
        languages:
          $ref: '#/components/schemas/FilterApplied'
        media_types:
          $ref: '#/components/schemas/FilterApplied'
        safe_search:
          $ref: '#/components/schemas/FilterApplied'
        source_kinds:
          $ref: '#/components/schemas/FilterApplied'
        source_independence:
          $ref: '#/components/schemas/FilterApplied'
        as_of_date:
          $ref: '#/components/schemas/FilterApplied'
    OperatorsApplied:
      type: object
      description: >-
        One member per operator, every member always present, its state
        `not_applicable` for an operator the query did not use; `alternatives`
        stands for the `or` operator, since `or` is a reserved word.
      required:
        - phrase
        - exclusion
        - alternatives
        - site
        - filetype
        - intitle
        - inurl
        - before
        - after
        - wildcard
      properties:
        phrase:
          $ref: '#/components/schemas/OperatorApplied'
        exclusion:
          $ref: '#/components/schemas/OperatorApplied'
        alternatives:
          $ref: '#/components/schemas/OperatorApplied'
        site:
          $ref: '#/components/schemas/OperatorApplied'
        filetype:
          $ref: '#/components/schemas/OperatorApplied'
        intitle:
          $ref: '#/components/schemas/OperatorApplied'
        inurl:
          $ref: '#/components/schemas/OperatorApplied'
        before:
          $ref: '#/components/schemas/OperatorApplied'
        after:
          $ref: '#/components/schemas/OperatorApplied'
        wildcard:
          $ref: '#/components/schemas/OperatorApplied'
    Stratum:
      type: object
      description: One source and language in the merge, with the leads it gave.
      required:
        - datasource_id
        - language
        - lead_count
      properties:
        datasource_id:
          type: string
          pattern: ^[a-z][a-z0-9_]{0,63}$
          description: The source, by its datasource id.
          examples:
            - web
        language:
          type: string
          description: The language, a BCP 47 tag.
          examples:
            - en
        lead_count:
          type: integer
          minimum: 0
          description: The leads from this source in this language.
    ModelStep:
      type: object
      description: One step a model, or a versioned recognizer, took in making the answer.
      required:
        - step
        - version
      properties:
        step:
          type: string
          description: >-
            Which step ran: `highlights`, the judged highlights; `json_schema`,
            the schema fill; `summary`, the summary; `recognition`, text read
            from a page with no text layer; `language_detection`, the languages
            chosen for that reading; `reranking`, the search's ranking;
            `discovery`, the search's choice of sources; `source_profile`, a
            publisher identified during the call. An open set.
          examples:
            - highlights
            - json_schema
            - summary
            - recognition
            - language_detection
            - reranking
            - discovery
            - source_profile
        version:
          type: string
          description: The step's version, so a result can be placed and compared.
          examples:
            - hl-2026-10
    TimeStamp:
      type: object
      description: >-
        Proof that the record existed at a moment: an RFC 3161 time-stamp token
        over one datum, the sha-256 of the record's fingerprint followed by the
        screenshot's digest, or of the fingerprint alone when no screenshot was
        made.
      required:
        - token
        - authority
      properties:
        token:
          type: string
          contentEncoding: base64
          description: The token, in base64.
        authority:
          type: string
          description: The name of the time-stamping authority that issued it.
    ProblemChange:
      type: object
      description: The fix as data. Each member is present when it applies.
      properties:
        field:
          type: string
          description: >-
            The field to change: a field of the operation `operation` names when
            it is present, else of this request.
          examples:
            - page_token
        allowed_values:
          type: array
          description: The values the field may take.
          items:
            type: string
        bounds:
          $ref: '#/components/schemas/Bound'
          description: The range the field may take.
        operation:
          type: string
          description: >-
            The operation to call instead, by its id, one of this contract's 22
            operation ids, `fetch_contents` for one; an open set.
          examples:
            - fetch_contents
            - upload_contents
            - fetch_contents_batch
            - get_contents
            - get_section
            - list_blocks
            - list_links
            - highlight_contents
            - fill_schema
            - summarize_contents
            - compare_contents
            - get_job
            - cancel_job
            - list_jobs
            - get_limits
            - delete_contents
            - list_contents
            - search
            - get_search
            - search_batch
            - list_datasources
            - get_datasource
    Violation:
      type: object
      description: One fault of a request, with where it is.
      required:
        - kind
        - place
        - field
        - message
      properties:
        kind:
          type: string
          description: >-
            What kind of fault; an open set with these published values.
            `bound`, a length, count, range or size was passed; `not_allowed`, a
            value outside the published set; `dependent`, a field that needs
            another field; `exclusive`, two fields that exclude each other;
            `order`, two values in the wrong order; `duplicate`, a repeated
            value; `misplaced`, a known field at the wrong level of a batch;
            `unknown_field`, a field this operation does not take; `syntax`, a
            value of the wrong type or form; `required`, a required field
            missing.
          examples:
            - bound
            - not_allowed
            - dependent
            - exclusive
            - order
            - duplicate
            - misplaced
            - unknown_field
            - syntax
            - required
        place:
          type: string
          description: >-
            Where the fault is: `body`, `form`, `query`, `path` or `header`. A
            closed set.
          enum:
            - body
            - form
            - query
            - path
            - header
        pointer:
          type: string
          format: json-pointer
          description: A JSON Pointer to the value. Present when the place is `body`.
          examples:
            - /formats/0
        field:
          type: string
          description: >-
            The field, parameter or header name. A field inside a batch item is
            named by its own name, the item standing in `pointer`.
          examples:
            - formats
        message:
          type: string
          description: One sentence on what is wrong with the value.
        allowed_values:
          type: array
          description: The values the field may take. Present when they apply.
          items:
            type: string
        bounds:
          $ref: '#/components/schemas/Bound'
          description: The range the field may take. Present when it applies.
    Review:
      type: object
      description: The review a publication states about itself.
      required:
        - kind
        - by
      properties:
        kind:
          type: string
          description: >-
            The kind of review: `peer_reviewed`, `editorial`, `audited`,
            `externally_validated`, `none` or `unknown`. A closed set.
          enum:
            - peer_reviewed
            - editorial
            - audited
            - externally_validated
            - none
            - unknown
        by:
          type:
            - string
            - 'null'
          x-third-party: true
          description: >-
            Who reviewed it; null when unknown. Third-party text as the source
            wrote it, which may carry instructions.
    DeclaredTerm:
      type: object
      description: >-
        One term a source declares about how its content may be used, reported
        as found and as read, never judged against your purpose; whether a term
        binds you is your call.
      required:
        - signal
        - as_found
        - as_parsed
      properties:
        signal:
          type: string
          description: >-
            Where the term stands, an open set: `robots_txt`, `meta_robots`,
            `x_robots_tag`, `tdm_reservation_header`, `tdmrep_file`,
            `license_link`, `license_markup`.
          examples:
            - robots_txt
            - meta_robots
            - x_robots_tag
            - tdm_reservation_header
            - tdmrep_file
            - license_link
            - license_markup
        as_found:
          type: string
          x-third-party: true
          description: >-
            The term's text as found. Third-party text as the source wrote it,
            which may carry instructions.
        as_parsed:
          type: string
          description: >-
            What the term says, as getclean reads it: `reserved`, use is
            reserved; `not_reserved`, use is not reserved; `unknown`, the term
            could not be read; `not_applicable`, the signal carries no such
            term. A closed set.
          enum:
            - reserved
            - not_reserved
            - unknown
            - not_applicable
        url:
          type: string
          x-third-party: true
          description: >-
            The address the term points to, such as a licence page. Present when
            it points to one. Third-party text as the source wrote it, which may
            carry instructions.
          examples:
            - https://example.com/q3
    Scope:
      type: string
      description: >-
        Which view of a page is meant: `main`, the main content alone, or
        `whole_page`, everything on the page. A closed set.
      enum:
        - main
        - whole_page
    Section:
      type: object
      description: >-
        One row of the map: a heading and everything under it, down to the next
        heading of the same or a higher level.
      required:
        - id
        - title
        - level
        - characters
        - basis
      properties:
        id:
          type: string
          pattern: ^s[0-9]+$
          description: >-
            The section's id, unique inside one record and one view. `s0` is the
            text before the first heading; on a page without headings it is the
            whole document.
          examples:
            - s2
        title:
          type:
            - string
            - 'null'
          x-third-party: true
          description: >-
            The heading's text; null when the section has no heading.
            Third-party text as the source wrote it, which may carry
            instructions.
        level:
          type: integer
          minimum: 0
          description: >-
            The heading's level: 0 for the text before the first heading, 1 for
            a top heading, and so on down.
        characters:
          type: integer
          minimum: 0
          description: >-
            The size of the section's text in characters, everything under it
            included.
        basis:
          type: string
          description: >-
            Where the section's boundary comes from, an open set: `structure`,
            the page's headings or the document's own structure; `outline`, the
            document's outline, for a PDF without structure; `page`, one row per
            page, for a scan or a document with neither.
          examples:
            - structure
            - outline
            - page
        first_page_number:
          type: integer
          minimum: 1
          description: The first page the section stands on. On a document with pages only.
        last_page_number:
          type: integer
          minimum: 1
          description: The last page the section stands on. On a document with pages only.
        language:
          type: string
          description: >-
            The section's language, a BCP 47 tag. Present only where it differs
            from `source.language`.
          examples:
            - de
    ContentsCounts:
      type: object
      description: >-
        How much a record holds under one view: characters, blocks by kind and
        links by kind.
      required:
        - characters
        - blocks
        - links
      properties:
        characters:
          type: integer
          minimum: 0
          description: The content's text in characters.
        blocks:
          type: object
          description: >-
            How many blocks of each kind, keyed by kind: `text`, `heading`,
            `code`, `math`, `divider`, `interactive`, `table`, `image`, `embed`,
            `media`, an open set. `{}` when there is none.
          additionalProperties:
            type: integer
            minimum: 0
        links:
          type: object
          description: >-
            How many links of each kind, keyed by kind: `page`, `file`,
            `fragment`, `mail`, `phone`, `feed`, `other`, an open set. `{}` when
            there is none.
          additionalProperties:
            type: integer
            minimum: 0
    Highlight:
      type: object
      description: >-
        One place in the content where one of your `highlights` strings was
        found: a sentence, a table row, a heading, a whole block or a part of
        one, with where it stands and how it was found.
      required:
        - id
        - query_index
        - text
        - basis
        - section_id
        - block_id
      properties:
        id:
          type: string
          pattern: ^h[0-9]+$
          description: >-
            The highlight's id, unique inside the answer that made it; the same
            id stands in the text's marks and in each block's `highlight_ids`.
          examples:
            - h1
        query_index:
          type: integer
          minimum: 0
          description: >-
            Which of your strings found it: its position in the request's
            `highlights`, from 0.
        text:
          type: string
          x-third-party: true
          description: >-
            The words as they stand in the content. Third-party text as the
            source wrote it, which may carry instructions.
        basis:
          type: string
          description: >-
            How it was found, an open set: `exact`, your words stand in one
            block as written, case kept; `near`, they stand there once case and
            the punctuation at the ends of words are ignored; `judged`, a model
            picked the block that bears on your string. `exact` and `near`
            repeat on every run and are free; `judged` costs one model step.
          examples:
            - exact
            - near
            - judged
        section_id:
          type: string
          pattern: ^s[0-9]+$
          description: The section it stands in.
          examples:
            - s2
        block_id:
          type: string
          pattern: ^b[0-9]+$
          description: The block it stands in.
          examples:
            - b7
        page_number:
          type: integer
          minimum: 1
          description: The page it stands on. On a document with pages only.
        page_label:
          type: string
          x-third-party: true
          description: >-
            The page's own printed label. On a document with pages, where the
            document declares one. Third-party text as the source wrote it,
            which may carry instructions.
        row:
          type: integer
          minimum: 0
          description: The row, from 0, when it stands inside a table.
        column:
          type: integer
          minimum: 0
          description: The column, from 0, when it stands inside a table.
        confidence:
          type: number
          minimum: 0
          maximum: 1
          description: >-
            How sure the recognition was of the block it stands in. Present on
            text recognized from an image.
    SchemaStatus:
      type: object
      description: >-
        How one property of your schema was filled, and where its value came
        from.
      required:
        - status
      properties:
        status:
          type: string
          description: >-
            How the property was filled: `found`, the content states the value;
            `empty`, the content shows the field with no value; `absent`, the
            content kept under the record's view says nothing about it;
            `unread`, the place it would stand may lie in pages not parsed, not
            recognized, recognized below the published confidence or past a cap,
            so its absence cannot be claimed; `failed`, the model could not fill
            it. An open set.
          examples:
            - found
            - empty
            - absent
            - unread
            - failed
        text:
          type: string
          x-third-party: true
          description: >-
            The words the value came from. Present on `found` and `empty`.
            Third-party text as the source wrote it, which may carry
            instructions.
        confidence:
          type: number
          minimum: 0
          maximum: 1
          description: >-
            How sure the recognition was of those words. Present when they were
            recognized from an image.
        section_id:
          type: string
          pattern: ^s[0-9]+$
          description: >-
            The section the words stand in. Present on `found` and `empty`, and
            on `unread` when the place is known.
          examples:
            - s2
        block_id:
          type: string
          pattern: ^b[0-9]+$
          description: The block the words stand in. Present as `section_id` is.
          examples:
            - b7
        page_number:
          type: integer
          minimum: 1
          description: >-
            The page the words stand on. Present as `section_id` is, on a
            document with pages.
        page_label:
          type: string
          x-third-party: true
          description: >-
            The page's own printed label. Present as `page_number` is, where the
            document declares one. Third-party text as the source wrote it,
            which may carry instructions.
        row:
          type: integer
          minimum: 0
          description: The row, from 0, when the words stand inside a table.
        column:
          type: integer
          minimum: 0
          description: The column, from 0, when the words stand inside a table.
    SourceCompact:
      type: object
      description: >-
        The source of a compact record; each member present and typed as
        `Source` gives it.
      required:
        - title
        - published_date
      properties:
        url:
          type: string
          x-third-party: true
          description: >-
            The address that was asked for; on an upload, the `captured_url`
            given. Absent on an upload sent without `captured_url`. On a record
            a search made, third-party text as the source wrote it, which may
            carry instructions.
          examples:
            - https://example.com/q3
        final_url:
          type: string
          x-third-party: true
          description: >-
            The address the fetch ended at, after every redirect. Absent on an
            upload. Third-party text as the source wrote it, which may carry
            instructions.
          examples:
            - https://example.com/q3
        title:
          type:
            - string
            - 'null'
          x-third-party: true
          description: >-
            The title as the source declares it; null when none came.
            Third-party text as the source wrote it, which may carry
            instructions.
        published_date:
          type:
            - string
            - 'null'
          format: date
          description: >-
            The date of publication as the source declares it, a full date; null
            when none.
        published_at:
          type: string
          format: date-time
          description: >-
            The moment of publication in UTC. Present when the page states a
            time with its zone.
    FilterApplied:
      type: object
      description: How one hard filter was applied on one source.
      required:
        - state
      properties:
        state:
          $ref: '#/components/schemas/FilterState'
          description: >-
            How it was applied: `native`, `emulated`, `skipped` or
            `not_applicable`, as `FilterState` defines them.
        how:
          type: string
          description: How getclean emulated it. Present on `emulated`.
    OperatorApplied:
      type: object
      description: How one operator was applied on one source.
      required:
        - state
      properties:
        state:
          $ref: '#/components/schemas/OperatorState'
          description: >-
            How it was applied: `native`, `emulated`, `dropped` or
            `not_applicable`, as `OperatorState` defines them.
    Bound:
      type: object
      description: >-
        The range a field takes. Each member is present where it applies; an
        integer field has integer values.
      properties:
        min:
          type: number
          description: The least value allowed.
        max:
          type: number
          description: The greatest value allowed.
        default_value:
          type: number
          description: >-
            The value used when the field is left out. Named `default_value`,
            since `default` is a reserved word in Java and C#.
        excluded_min:
          type: number
          description: >-
            The first value of a gap inside the range, where no value is
            allowed. `max_characters` allows 0 and then 1,000 upward, so its gap
            runs from 1 to 999.
        excluded_max:
          type: number
          description: The last value of a gap inside the range, 999 for `max_characters`.
    FilterState:
      type: string
      description: >-
        How a hard filter was applied on one source; `native`, by the source;
        `emulated`, by getclean after the fact; `skipped`, the source skipped
        for it; `not_applicable`, the filter not sent. A closed set.
      enum:
        - native
        - emulated
        - skipped
        - not_applicable
    OperatorState:
      type: string
      description: >-
        How a query operator was applied on one source: `native`, by the source;
        `emulated`, by getclean; `dropped`, left out on that source;
        `not_applicable`, the query did not use it. A closed set.
      enum:
        - native
        - emulated
        - dropped
        - not_applicable
  headers:
    RequestId:
      description: >-
        This call's id, a `req_` id, on every response. The body repeats it as
        `request_id` where a body is sent. A replayed answer carries this call's
        id, never the first call's. Quote it when you ask about a call.
      required: true
      schema:
        type: string
        pattern: ^req_[A-Za-z0-9]{22}$
    RateLimit:
      description: >-
        What is left of your quota, in the form of
        `draft-ietf-httpapi-ratelimit-headers-11`, two items named as in
        `RateLimit-Policy`: `"requests";r=<left>;t=<seconds>`, the requests left
        and the seconds to the window's reset; `"concurrency";r=<left>`, the
        calls you may still have in flight. Sent on every response but a `401`.
        `get_limits` returns the same figures in the body as `rates`. A `429`
        names the policy it exceeded in `detail`: `rate-limit-exceeded` for
        requests, `concurrency-limit-exceeded` for concurrency.
      required: true
      schema:
        type: string
    RateLimitPolicy:
      description: >-
        Your key's rate policy, in the form of
        `draft-ietf-httpapi-ratelimit-headers-11`, two items:
        `"requests";q=<requests_per_minute>;w=60`, the requests allowed per
        minute; `"concurrency";q=<concurrency>;qu="concurrent-requests"`, the
        calls allowed in flight at once. Sent on every response but a `401`.
      required: true
      schema:
        type: string
    Sunset:
      description: >-
        The moment a resource is retired, as an IMF-fixdate, sent on every
        answer of that resource once its retirement is announced, RFC 8594. It
        is never used for a retiring version of getclean itself: that is
        announced by the notice `version_retiring` and by `Version.retires_at`,
        since a client that knows only RFC 8594 would read `Sunset` as the end
        of the resource.
      required: false
      schema:
        type: string
    Deprecation:
      description: >-
        The moment a resource's or an element's retirement was announced, as a
        Structured Field Date, `@` and the seconds, RFC 9745. Sent on every
        answer of that resource or element from the announcement on, beside
        `Sunset` once the end is set.
      required: false
      schema:
        type: string
    WwwAuthenticateRequired:
      description: >-
        The `WWW-Authenticate` value of a `401`, which tells a client where to
        sign in. With no credential sent: `Bearer realm="getclean",
        resource_metadata="https://api.getclean.ai/.well-known/oauth-protected-resource"`.
        With a credential sent and rejected: the same with
        `error="invalid_token"` added, RFC 6750 section 3 and RFC 9728 section
        5.1. The document it names is the API's protected resource metadata,
        served to anyone outside the versioned paths; an agent that arrives with
        nothing follows it to the issuer and its device sign-in.
      required: true
      schema:
        type: string
    WwwAuthenticate:
      description: >-
        Sent on a `403` only when the type is `insufficient-scope`: `Bearer
        realm="getclean", error="insufficient_scope",
        resource_metadata="https://api.getclean.ai/.well-known/oauth-protected-resource"`,
        with the `scope` attribute naming every scope the call needs, the same
        list as the body's `scopes_required`. Never sent on the other `403`s.
      required: false
      schema:
        type: string
    RetryAfterRequired:
      description: >-
        Seconds to wait before asking again, an integer of 1 or more, repeated
        in the body as `retry_after_seconds`. Always sent on `202`, `429` and
        `503`.
      required: true
      schema:
        type: integer
        minimum: 1
  responses:
    Problem400:
      description: >-
        The request could not be read, or a value outside its body is wrong, so
        nothing was done. Two problem types answer `400`.

        - `invalid-request`, The request is invalid: the body did not parse, a
        path, query or header value is wrong, an id has the wrong form, or a
        required header is missing. Each fault stands in `violations` with where
        it is.

        - `page-token-invalid`, The page token is invalid: the token is unknown,
        expired, belongs to another record, or the filter changed between pages.
        `change.field` names `page_token`; drop the token and start the list
        again.


        A plain HTTP request is answered `invalid-request` over that connection,
        with `detail` naming the HTTPS URL, never a redirect.
      headers:
        Request-Id:
          $ref: '#/components/headers/RequestId'
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimitPolicy'
        Sunset:
          $ref: '#/components/headers/Sunset'
        Deprecation:
          $ref: '#/components/headers/Deprecation'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    Problem401:
      description: >-
        `unauthorized`, The key is missing or rejected. `WWW-Authenticate`
        carries the challenge, and `detail` says which case it is:

        - No credential sent: "No credential was sent: send Authorization:
        Bearer with an API key from https://app.getclean.ai, or sign in as
        https://auth.getclean.ai/auth.md describes."

        - A credential sent and rejected: "The credential is unknown, expired or
        revoked: refresh the token, sign in again, or use another key."

        - A credential in the query string only: "A credential in the query
        string is ignored: send it in the Authorization header as Bearer."


        The credential is never echoed. No `RateLimit` or `RateLimit-Policy`
        header is sent, since no account's quota applies.
      headers:
        Request-Id:
          $ref: '#/components/headers/RequestId'
        Sunset:
          $ref: '#/components/headers/Sunset'
        Deprecation:
          $ref: '#/components/headers/Deprecation'
        WWW-Authenticate:
          $ref: '#/components/headers/WwwAuthenticateRequired'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    Problem403:
      description: >-
        The key was accepted but is not allowed to do this, by its scopes, its
        policy or its money. Six problem types answer `403`; the first is yours
        to fix when you hold an access token, and the rest are the account
        owner's.

        - `insufficient-scope`, The key lacks a scope this call needs: every
        scope the call needs is in `scopes_required` and in `WWW-Authenticate`.
        With an access token, ask the person for the scope again; with an API
        key, the account owner adds it.

        - `policy-limit-exceeded`, The key's policy forbids this: a domain, a
        setting, a minimum or a cost cap the key's policy forbids, a request
        looser than the policy, or the key's cap below the smallest call, with
        `minimum_cap`.

        - `datasource-access-required`, The datasource needs a registered login.

        - `credit-exhausted`, The credit is exhausted: `balance`,
        `amount_needed` and `funding_url`.

        - `run-budget-exhausted`, The run's budget is exhausted:
        `run_budget_remaining`, `amount_needed` and `funding_url`.

        - `key-budget-exhausted`, The key's budget is exhausted:
        `key_budget_remaining`, `amount_needed` and `funding_url`.


        `amount_needed` is what the limit that binds lacks for the smallest
        call: the call's price less what the limit holds.
      headers:
        Request-Id:
          $ref: '#/components/headers/RequestId'
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimitPolicy'
        Sunset:
          $ref: '#/components/headers/Sunset'
        Deprecation:
          $ref: '#/components/headers/Deprecation'
        WWW-Authenticate:
          $ref: '#/components/headers/WwwAuthenticate'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    Problem404:
      description: >-
        `not-found`, Not found: the record, job, datasource, section or block an
        id names does not exist for this account; `change.field` says which id.
        An id of another account's record gets the same `404` with the same
        body, kept or expired. A replay whose record was deleted is `404` too,
        with `detail` naming the deletion. RFC 9110 reserves `404` and `410` for
        the target resource; here `404` also answers an id named in a body or a
        query, since the thing named is what is missing, a stated departure. An
        unknown `run_id` is not a `404`: it is `422 invalid-field` in a body and
        `400 invalid-request` in a query, kind `not_allowed`, since a run is a
        setting of the key and not a resource here.
      headers:
        Request-Id:
          $ref: '#/components/headers/RequestId'
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimitPolicy'
        Sunset:
          $ref: '#/components/headers/Sunset'
        Deprecation:
          $ref: '#/components/headers/Deprecation'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    Problem410:
      description: >-
        What the id names has expired. Three problem types answer `410`, each
        for 30 days after the end and to the owning account only; after that the
        id is `404`. Another account's id gets the `404` from the start, with
        the same body.

        - `contents-expired`, The record has expired: `expired_at` is the moment
        it expired; `change.operation` `fetch_contents` with `change.field`
        `url` says the page is fetched again.

        - `search-expired`, The search has expired: `change.operation` `search`.

        - `job-expired`, The job has expired: `change.operation`
        `upload_contents`.


        The answer carries the moment it expired and never the record's URL or
        the search's question.
      headers:
        Request-Id:
          $ref: '#/components/headers/RequestId'
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimitPolicy'
        Sunset:
          $ref: '#/components/headers/Sunset'
        Deprecation:
          $ref: '#/components/headers/Deprecation'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          examples:
            get_contents.contents-expired:
              summary: A record read after it expired
              value:
                type: https://api.getclean.ai/problems/contents-expired
                title: The record has expired
                status: 410
                detail: The record has expired; fetch the page again.
                instance: https://api.getclean.ai/requests/req_01QEihyEKxtyS4rknqVJEV
                request_id: req_01QEihyEKxtyS4rknqVJEV
                who_must_act: caller
                retryable: false
                expired_at: '2026-11-06T12:00:00Z'
                change:
                  operation: fetch_contents
                  field: url
    Problem429:
      description: >-
        The key is calling too often, or has too many calls in flight. Two
        problem types answer `429`. `detail` names the policy exceeded;
        `Retry-After` and `retry_after_seconds` say when to ask again; the SDKs
        retry both for you.

        - `rate-limit-exceeded`, The rate limit is exceeded: more requests in
        the minute than the requests policy allows.

        - `concurrency-limit-exceeded`, Too many calls are in flight: more calls
        at once than the concurrency policy allows.
      headers:
        Request-Id:
          $ref: '#/components/headers/RequestId'
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimitPolicy'
        Sunset:
          $ref: '#/components/headers/Sunset'
        Deprecation:
          $ref: '#/components/headers/Deprecation'
        Retry-After:
          $ref: '#/components/headers/RetryAfterRequired'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    Problem500:
      description: >-
        `internal-error`, The service failed: getclean's own failure, never a
        source's. getclean must fix it; the SDKs do not retry it. Quote the
        `Request-Id` when you report it.
      headers:
        Request-Id:
          $ref: '#/components/headers/RequestId'
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimitPolicy'
        Sunset:
          $ref: '#/components/headers/Sunset'
        Deprecation:
          $ref: '#/components/headers/Deprecation'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    Problem503:
      description: >-
        `overloaded`, The service is overloaded: the request could not start
        within the published queue bound, or a batch item was not started.
        `Retry-After` and `retry_after_seconds` say when to ask again; ask again
        with the same key after that wait, and once the first call has answered,
        the same key returns its answer.
      headers:
        Request-Id:
          $ref: '#/components/headers/RequestId'
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimitPolicy'
        Sunset:
          $ref: '#/components/headers/Sunset'
        Deprecation:
          $ref: '#/components/headers/Deprecation'
        Retry-After:
          $ref: '#/components/headers/RetryAfterRequired'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      description: >-
        An API key from https://app.getclean.ai, or an access token issued by
        https://auth.getclean.ai/realms/getclean, sent as `Authorization: Bearer
        <key>` on every call. The scopes a key carries and what a 401 and a 403
        say are on the keys and sign-in page.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.