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

> Read a job, or wait for it to finish, free. The answer comes at the final state or when `wait_seconds` ends, with the job as it stands; it is `200` when the job failed too, with the failure inside. `Retry-After` and `retry_after_seconds` come on every answer that is not final. Once `contents_id` is set, `get_contents` reads the record; `cancel_job` asks the job to stop.

## What it costs

The key needs `jobs:read`. The call is free. The answer is `200` with `Job`, never cached. A `HEAD` on this path is answered at once and does not wait.

## Refused before any work

A value outside its range: `400 invalid-request`, `bound`. An id of the wrong kind: `400 invalid-request`, before any lookup. An unknown query parameter: `400 invalid-request`, `unknown_field`.

## Problem types

* 400 `invalid-request`, The request 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 job.
* 410 `job-expired`, The job has expired: the job ended more than 30 days ago. The answer comes for 30 more days, to the owning account only, with `expired_at` and `change` naming `upload_contents`; 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/jobs/{job_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/jobs/{job_id}:
    get:
      summary: Get job
      description: >-
        Read a job, or wait for it to finish, free. The answer comes at the
        final state or when `wait_seconds` ends, with the job as it stands; it
        is `200` when the job failed too, with the failure inside. `Retry-After`
        and `retry_after_seconds` come on every answer that is not final. Once
        `contents_id` is set, `get_contents` reads the record; `cancel_job` asks
        the job to stop.
      operationId: get_job
      parameters:
        - $ref: '#/components/parameters/Traceparent'
        - name: job_id
          in: path
          required: true
          description: The job, a `job_` id as `upload_contents` returned it.
          schema:
            type: string
            pattern: ^job_[A-Za-z0-9]{22}$
          example: job_8Rt2mqXKclxu58MCwLkSCV
        - name: wait_seconds
          in: query
          required: false
          description: >-
            The most seconds to wait for the job to finish, 0 to 90; the answer
            comes at the final state or when the wait ends, with the current
            state. Default 0, no wait.
          schema:
            type: number
            minimum: 0
            maximum: 90
            default: 0
      responses:
        '200':
          description: >-
            The job in its current state; `Retry-After` and
            `retry_after_seconds` while it is not finished; once finished, its
            `outcome`, its `contents_id` or its `problem`, and its final `cost`.
          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/RetryAfter'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Job'
              examples:
                get_job.completed:
                  summary: >-
                    A completed job whose record is partial, two pages having
                    failed
                  value:
                    id: job_8Rt2mqXKclxu58MCwLkSCV
                    kind: upload_contents
                    state: completed
                    finished: true
                    counts:
                      parsed_count: 310
                      failed_count: 2
                      remaining_count: 0
                    cost:
                      ceiling:
                        amount: '1.0000'
                        currency: USD
                      actual:
                        amount: '0.3300'
                        currency: USD
                      units:
                        contents: 1
                        document_pages: 310
                        recognized_pages: 3
                      replayed: false
                    outcome:
                      kind: partial
                      reason: pages_failed
                    contents_id: cnt_f9a1LknFzePvIKv1pEkejs
                    created_at: '2026-11-04T10:02:11Z'
                    updated_at: '2026-11-04T10:14:52Z'
                    expires_at: '2026-12-04T10:14:52Z'
                    request_id: req_01Qm89u0cStrgTL7bxmqKa
        '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
  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
    RetryAfter:
      description: >-
        Seconds to wait before asking again, an integer of 1 or more, repeated
        in the body as `retry_after_seconds`. On a `200` of `get_job` or
        `cancel_job` it is sent only while the job is not finished; on a `409`
        only when the type is `idempotency-key-in-flight`.
      required: false
      schema:
        type: integer
        minimum: 1
    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
  schemas:
    Job:
      type: object
      description: >-
        A parse that outlives its request. `completed` when its record is
        delivered or partial, `failed` otherwise, with `problem` set when
        nothing was made; `canceled` keeps and bills the pages done. Kept 30
        days after its end, then `410 job-expired` for 30 days, then `404`. A
        job carries no notices and no version.
      required:
        - id
        - kind
        - state
        - finished
        - counts
        - cost
        - created_at
        - updated_at
        - request_id
      properties:
        id:
          type: string
          pattern: ^job_[A-Za-z0-9]{22}$
          description: >-
            The job's id, `job_` and 22 random characters; another account's id
            answers `404`.
          examples:
            - job_8Rt2mqXKclxu58MCwLkSCV
        kind:
          type: string
          description: The operation that started the job, `upload_contents`; an open set.
          examples:
            - upload_contents
        state:
          type: string
          description: >-
            The job's state: `queued`, `running`, `completed`, `failed` or
            `canceled`; the last three are final. An open set.
          examples:
            - queued
            - running
            - completed
            - failed
            - canceled
        finished:
          type: boolean
          description: True once the state is final.
        stage:
          type: string
          description: >-
            What the job is doing now, `parsing` or `recognizing`; an open set.
            Absent on `queued` and when final.
          examples:
            - parsing
            - recognizing
        counts:
          $ref: '#/components/schemas/JobCounts'
          description: >-
            The pages parsed, failed and remaining, adding up to `pages.count`;
            zeros while the job is queued or the count unread.
        cost:
          $ref: '#/components/schemas/Cost'
          description: >-
            The units so far on every read, the final figure once `finished`;
            zero on a cancel with no page done.
        outcome:
          $ref: '#/components/schemas/Outcome'
          description: The record's outcome. Present once a record exists.
        retry_after_seconds:
          type: integer
          minimum: 1
          description: >-
            Seconds to wait before reading again, equal to the `Retry-After`
            header of `get_job` and `cancel_job`; inside a `JobPage`, each job's
            own wait. Absent once final.
        contents_id:
          type: string
          pattern: ^cnt_[A-Za-z0-9]{22}$
          description: >-
            The record the job made, read by `get_contents`. Present once a
            record exists.
          examples:
            - cnt_f9a1LknFzePvIKv1pEkejs
        problem:
          $ref: '#/components/schemas/Problem'
          description: >-
            Why the job failed before a record existed, without `status`, its
            `request_id` and `instance` the upload's. Present only on a job that
            failed with no record.
        created_at:
          type: string
          format: date-time
          description: When the job started, RFC 3339 in UTC.
          examples:
            - '2026-11-04T10:02:11Z'
        updated_at:
          type: string
          format: date-time
          description: When the job last changed, RFC 3339 in UTC.
          examples:
            - '2026-11-04T10:14:52Z'
        expires_at:
          type: string
          format: date-time
          description: >-
            When the job expires, 30 days after it ended, RFC 3339 in UTC.
            Absent until final.
          examples:
            - '2026-12-04T10:14:52Z'
        request_id:
          type: string
          pattern: ^req_[A-Za-z0-9]{22}$
          description: >-
            The id of the call this copy of the job came back in, the same as
            that call's `Request-Id` header.
          examples:
            - req_01Qm89u0cStrgTL7bxmqKa
    JobCounts:
      type: object
      description: >-
        The pages of a job; the three add up to `pages.count`, on which a format
        without pages counts `bounds.contents.document_page_characters`
        characters as one page.
      required:
        - parsed_count
        - failed_count
        - remaining_count
      properties:
        parsed_count:
          type: integer
          minimum: 0
          description: Pages parsed without failure; the bill counts these.
        failed_count:
          type: integer
          minimum: 0
          description: Pages that could not be parsed.
        remaining_count:
          type: integer
          minimum: 0
          description: Pages not yet parsed.
    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.
    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.
    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
    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
    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.
    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`.
  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.