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

# Run a read-only tool on a list of inputs

> Run one read-only tool on 1 to 100 inputs in one call, and return the batch at once.

> [accordion] Details
>
> Business accounts only.
>
> * Each input runs as its own run, and items answer in the order you sent them.
>
> * An input that doesn't fit the tool's input schema never runs: its item answers invalid\_input with the problem, and the other items still run.
>
> * Follow the batch with GET /v1/batches/\{id} until its status is completed. Retry-After suggests when to read it again.
>
> * A tool that changes the website is refused with tool\_not\_read\_only before anything runs.
>
> * **Callers:** an API key, an integration's API key, an MCP OAuth token or a Dashboard session.
>
> * **Permission:** `runs:create`.
>
> * **Effect:** Changes nothing.
>
> * **Errors:** [`idempotency_conflict`](https://docs.pomerado.ai/errors#idempotency_conflict), [`quota_exceeded`](https://docs.pomerado.ai/errors#quota_exceeded), [`quota_expired`](https://docs.pomerado.ai/errors#quota_expired), [`acceptance_unknown`](https://docs.pomerado.ai/errors#acceptance_unknown), [`not_found`](https://docs.pomerado.ai/errors#not_found), [`save_forbidden`](https://docs.pomerado.ai/errors#save_forbidden), [`account_selection_required`](https://docs.pomerado.ai/errors#account_selection_required), [`saved_login_conflict`](https://docs.pomerado.ai/errors#saved_login_conflict), [`login_identity_conflict`](https://docs.pomerado.ai/errors#login_identity_conflict), [`legacy_duplicate_saved_logins`](https://docs.pomerado.ai/errors#legacy_duplicate_saved_logins), [`saved_login_unsettled`](https://docs.pomerado.ai/errors#saved_login_unsettled), [`not_configured`](https://docs.pomerado.ai/errors#not_configured), [`service_account_not_allowed`](https://docs.pomerado.ai/errors#service_account_not_allowed), [`service_account_cap_reached`](https://docs.pomerado.ai/errors#service_account_cap_reached), [`unsupported_login_field`](https://docs.pomerado.ai/errors#unsupported_login_field), [`site_not_supported`](https://docs.pomerado.ai/errors#site_not_supported), [`payment_card_refused`](https://docs.pomerado.ai/errors#payment_card_refused), [`raw_card_refused`](https://docs.pomerado.ai/errors#raw_card_refused), [`file_too_large`](https://docs.pomerado.ai/errors#file_too_large), [`file_type_refused`](https://docs.pomerado.ai/errors#file_type_refused), [`file_unavailable`](https://docs.pomerado.ai/errors#file_unavailable), [`file_limit_exceeded`](https://docs.pomerado.ai/errors#file_limit_exceeded), [`file_fetch_failed`](https://docs.pomerado.ai/errors#file_fetch_failed), [`tool_not_read_only`](https://docs.pomerado.ai/errors#tool_not_read_only), [`business_account_required`](https://docs.pomerado.ai/errors#business_account_required), and the [errors any request can get](https://docs.pomerado.ai/errors.md).


## OpenAPI

````yaml /api-reference/openapi.json post /v1/runs/read-only/batch
openapi: 3.1.0
info:
  title: Pomerado API
  version: '1'
  description: >-
    Run and build website tools, follow their jobs, and manage logins, API keys
    and webhooks. Authenticate with a Pomerado API key (pom_…), an MCP OAuth
    token or a Dashboard session as a Bearer token.
servers:
  - url: https://api.pomerado.ai
security: []
tags:
  - name: account
    x-group: Account
  - name: api_keys
    x-group: API keys
  - name: connected_apps
    x-group: Connected apps
  - name: usage
    x-group: Usage
  - name: quota
    x-group: Quota
  - name: spend_controls
    x-group: Spend controls
  - name: usage_alerts
    x-group: Usage alerts
  - name: usage_summary
    x-group: Usage summary
  - name: billing
    x-group: Billing
  - name: integrations
    x-group: Integrations
  - name: connect
    x-group: Connect
  - name: code
    x-group: Code
  - name: logins
    x-group: Saved logins
  - name: two_factor
    x-group: 2FA
  - name: login_access
    x-group: Login access
  - name: tools
    x-group: Tools
  - name: shapes
    x-group: Shapes
  - name: webhooks
    x-group: Webhooks
  - name: payer_profiles
    x-group: Payer profiles
  - name: payer_addresses
    x-group: Payer addresses
  - name: payment_methods
    x-group: Payment methods
  - name: runs
    x-group: Runs
  - name: builds
    x-group: Builds
  - name: jobs
    x-group: Jobs
  - name: suggestions
    x-group: Suggestions
  - name: audit
    x-group: Audit
  - name: files
    x-group: Files
  - name: team
    x-group: Team
  - name: sso
    x-group: Single sign-on
  - name: issue_reports
    x-group: Problem reports
paths:
  /v1/runs/read-only/batch:
    post:
      tags:
        - runs
      summary: Run a read-only tool on a list of inputs
      description: >-
        Run one read-only tool on 1 to 100 inputs in one call, and return the
        batch at once.
      operationId: runs.create_read_only_batch
      parameters:
        - name: Idempotency-Key
          in: header
          required: false
          description: >-
            Repeat a request safely: the same key and body answer the first
            request's job again with Idempotent-Replayed: true; the same key
            with a different body answers idempotency_conflict.
          schema:
            type: string
            description: 1 to 200 letters, digits, _ or -, such as a UUID
            pattern: ^[A-Za-z0-9_-]{1,200}$
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - tool_id
              properties:
                tool_id:
                  type: string
                  description: The ID of the read tool to run, from a tool search
                  pattern: ^tool_[0-9a-f]{32}$
                items:
                  type: array
                  items:
                    type: object
                    required:
                      - input
                    properties:
                      input:
                        type: object
                        required: []
                        properties: {}
                        additionalProperties:
                          $id: /schemas/unknown
                        description: >-
                          This item's input, as the tool's input_schema
                          describes
                      key:
                        type: string
                        description: >-
                          Your own name for this item, 1 to 128 characters,
                          unique in the batch, echoed back
                        minLength: 1
                        maxLength: 128
                    additionalProperties: false
                  description: >-
                    1 to 100 items, each its input and an optional key. Send
                    items or inputs, not both
                  minItems: 1
                  maxItems: 100
                inputs:
                  type: array
                  items:
                    type: object
                    required: []
                    properties: {}
                    additionalProperties:
                      $id: /schemas/unknown
                  description: >-
                    1 to 100 inputs, for items without keys. Send items or
                    inputs, not both
                  minItems: 1
                  maxItems: 100
                defaults:
                  type: object
                  required: []
                  properties: {}
                  additionalProperties:
                    $id: /schemas/unknown
                  description: Input fields every item shares; an item's own fields win
                redact_at_rest:
                  type: boolean
                  description: >-
                    Staging and preview only: true seals what this job stores
                    and redacts it once it settles, false keeps it readable,
                    overriding the environment's setting. Production refuses a
                    request that names it with invalid_request.
                shape:
                  allOf:
                    - $ref: '#/components/schemas/shape_id'
                  description: >-
                    Your saved shape of this tool, to get every item's result in
                    that form; each item's job's shape says if it applied.
              additionalProperties: false
      responses:
        '200':
          description: >-
            The batch this Idempotency-Key already started, with
            Idempotent-Replayed: true
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Batch'
        '202':
          description: The new batch, its items queued in input order
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Batch'
        '400':
          description: >-
            unsupported_login_field, raw_card_refused, tool_not_read_only,
            invalid_request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: unauthorized, reauthentication_required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: >-
            save_forbidden, service_account_not_allowed, site_not_supported,
            payment_card_refused, business_account_required, forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: >-
            idempotency_conflict, quota_expired, account_selection_required,
            saved_login_conflict, login_identity_conflict,
            legacy_duplicate_saved_logins, saved_login_unsettled,
            file_unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '410':
          description: moved_to_team
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '413':
          description: file_too_large, file_limit_exceeded, request_too_large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '415':
          description: file_type_refused
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: file_fetch_failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: quota_exceeded, service_account_cap_reached
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: internal_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '501':
          description: not_configured
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: acceptance_unknown, temporarily_unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - bearer: []
components:
  schemas:
    shape_id:
      type: string
      description: 'a shape ID: shp_ and 32 lowercase hex digits'
      examples:
        - shp_0f8e2d1c4b3a49e8a7f6e5d4c3b2a190
    Batch:
      type: object
      required:
        - id
        - type
        - status
        - tool_id
        - counts
        - items
        - more_results
        - created_at
        - updated_at
        - completed_at
      properties:
        id:
          $ref: '#/components/schemas/batch_id'
        type:
          type: string
          enum:
            - batch
        status:
          type: string
          enum:
            - running
            - completed
            - cancelled
        tool_id:
          type: string
        counts:
          type: object
          required:
            - total
            - queued
            - running
            - succeeded
            - failed
            - cancelled
          properties:
            total:
              $ref: '#/components/schemas/Int'
            queued:
              $ref: '#/components/schemas/Int'
            running:
              $ref: '#/components/schemas/Int'
            succeeded:
              $ref: '#/components/schemas/Int'
            failed:
              $ref: '#/components/schemas/Int'
            cancelled:
              $ref: '#/components/schemas/Int'
          additionalProperties: false
        items:
          type: array
          items:
            $ref: '#/components/schemas/BatchItem'
        more_results:
          type: boolean
          description: >-
            true when finished items' results were left out to keep this answer
            under 1 MiB: read the batch again for them
        created_at:
          $ref: '#/components/schemas/Date'
        updated_at:
          $ref: '#/components/schemas/Date'
        completed_at:
          anyOf:
            - $ref: '#/components/schemas/Date'
            - type: 'null'
      additionalProperties: false
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
            - retryable
            - docs_url
          properties:
            code:
              type: string
            message:
              type: string
            retryable:
              type: boolean
            docs_url:
              type: string
            details:
              type: object
              required: []
              properties: {}
              additionalProperties:
                $id: /schemas/unknown
          additionalProperties: false
      additionalProperties: false
    batch_id:
      type: string
      description: 'a batch ID: batch_ and 32 lowercase hex digits'
      examples:
        - batch_0f8e2d1c4b3a49e8a7f6e5d4c3b2a190
    Int:
      type: integer
      description: an integer
    BatchItem:
      type: object
      required:
        - index
        - key
        - status
        - job
        - error
      properties:
        index:
          $ref: '#/components/schemas/Int'
        key:
          anyOf:
            - type: string
            - type: 'null'
        status:
          type: string
          enum:
            - queued
            - running
            - succeeded
            - failed
            - cancelled
        job:
          anyOf:
            - $ref: '#/components/schemas/Job'
            - type: 'null'
          description: >-
            The item's run, as GET /v1/jobs/{id} answers it; null when the item
            never ran
        error:
          anyOf:
            - $ref: '#/components/schemas/Error'
            - type: 'null'
          description: >-
            Why the item never ran, such as invalid_input for its own input;
            else null
      additionalProperties: false
    Date:
      type: string
      description: a string to be decoded into a Date
    Job:
      type: object
      required:
        - id
        - type
        - status
        - tool_id
        - input_request
        - result
        - result_status
        - result_expires_at
        - write_status
        - login_save
        - error
        - message
        - maintenance
        - build
        - watch_url
        - created_at
        - updated_at
        - completed_at
      properties:
        id:
          $ref: '#/components/schemas/job_id'
        type:
          type: string
          enum:
            - run
            - build
        status:
          type: string
          enum:
            - queued
            - running
            - needs_input
            - paused
            - succeeded
            - failed
            - cancelled
        tool_id:
          anyOf:
            - type: string
            - type: 'null'
        input_request:
          anyOf:
            - $ref: '#/components/schemas/InputRequest'
            - type: 'null'
        pause:
          $ref: '#/components/schemas/JobPause'
        result:
          $id: /schemas/unknown
        result_file:
          anyOf:
            - $ref: '#/components/schemas/ResultFile'
            - type: 'null'
        result_preview:
          $id: /schemas/unknown
        result_status:
          anyOf:
            - type: string
              enum:
                - available
                - delivered
                - expired
            - type: 'null'
        result_expires_at:
          anyOf:
            - $ref: '#/components/schemas/Date'
            - type: 'null'
        write_status:
          anyOf:
            - type: string
              enum:
                - not_attempted
                - may_have_applied
                - applied
                - not_applied
            - type: 'null'
          description: >-
            Whether a write tool's run, or a write build, changed the website.
            Null for a read, or while a repair is still working on a run's write
            that may have applied: the repair may still complete it, and once it
            ends this says what happened
        write_progress:
          anyOf:
            - type: string
              enum:
                - no_change
                - signed_in_only
                - may_have_submitted
                - submitted
            - type: 'null'
        login_save:
          anyOf:
            - type: object
              required:
                - status
                - login_id
                - reason
              properties:
                status:
                  type: string
                  enum:
                    - saved
                    - not_saved
                    - failed
                login_id:
                  anyOf:
                    - type: string
                    - type: 'null'
                reason:
                  anyOf:
                    - type: string
                    - type: 'null'
                missing:
                  type: string
                  enum:
                    - logins:manage
                  description: >-
                    With reason account_lacks_manage, consent_lacks_manage or
                    grant_lacks_manage: the permission the login's save lacked.
                grant_hint:
                  type: string
                  description: What to grant so a login answered for a job is saved.
              additionalProperties: false
            - type: 'null'
        error:
          anyOf:
            - $ref: '#/components/schemas/Error'
            - type: 'null'
        message:
          anyOf:
            - type: string
            - type: 'null'
        stop_reason:
          type: string
          enum:
            - cancel_requested
            - access_revoked
            - account_deleted
            - logins_unavailable
          description: >-
            Why a job told to stop stops, present while it stops (status
            running) and once it ended cancelled: cancel_requested when a cancel
            of this job arrived (from its caller, the account's owner or
            Pomerado support), access_revoked when the access that started it
            was revoked (its app's connection, API key, session or access to its
            saved login), account_deleted, or logins_unavailable when the
            account's saved logins became unavailable. Absent otherwise, and
            from an older backend
        stopped_after:
          type: string
          description: >-
            A write that succeeded with the website's refusal after an earlier
            step: that step's name. The website may have kept something from it,
            as message says
        maintenance:
          anyOf:
            - type: object
              required:
                - status
                - result_recovered
                - message
                - deadline_at
              properties:
                status:
                  type: string
                  enum:
                    - repairing
                    - repaired
                    - incomplete
                result_recovered:
                  type: boolean
                message:
                  type: string
                deadline_at:
                  anyOf:
                    - type: string
                    - type: 'null'
                reason:
                  type: string
                  description: >-
                    One sentence for the user saying what broke and started the
                    repair, in Pomerado's fixed words. Absent from an older
                    backend, or when Pomerado recorded no failure for the run
                now:
                  $ref: '#/components/schemas/JobMaintenanceNow'
                waiting_for_repair:
                  type: boolean
                  enum:
                    - true
                  description: >-
                    Present, as true, while the run waits behind another repair
                    of its tool, which runs first. Each time a repair publishes
                    a fixed tool, Pomerado runs the task again on it, and
                    repairs the tool for this run if it still fails. Absent
                    otherwise, and from an older backend
                change_in_progress:
                  type: boolean
                  enum:
                    - true
                  description: >-
                    Present, as true, with waiting_for_repair while the repair
                    the run waits behind is a change to the tool that someone
                    requested. When the change publishes, Pomerado runs the task
                    again on the changed tool; deadline_at leaves the change its
                    time to finish. Absent otherwise, and from an older backend
                input_refusal:
                  $ref: '#/components/schemas/JobMaintenanceInputRefusal'
              additionalProperties: false
            - type: 'null'
        build:
          anyOf:
            - $ref: '#/components/schemas/JobBuild'
            - type: 'null'
        purchase:
          type: object
          required:
            - id
            - status
            - amount
            - merchant_origin
          properties:
            id:
              type: string
            status:
              type: string
              enum:
                - created
                - awaiting_cardholder
                - ready
                - filled
                - succeeded
                - declined
                - uncertain
                - not_charged
            max_amount:
              type: object
              required:
                - amount
                - currency
              properties:
                amount:
                  type: string
                currency:
                  type: string
                  enum:
                    - AUD
                    - BRL
                    - CAD
                    - CHF
                    - CZK
                    - DKK
                    - EUR
                    - GBP
                    - HKD
                    - INR
                    - JPY
                    - KRW
                    - MXN
                    - NOK
                    - NZD
                    - PLN
                    - SEK
                    - SGD
                    - USD
                    - ZAR
              additionalProperties: false
            amount:
              type: object
              required:
                - amount
                - currency
              properties:
                amount:
                  type: string
                currency:
                  type: string
                  enum:
                    - AUD
                    - BRL
                    - CAD
                    - CHF
                    - CZK
                    - DKK
                    - EUR
                    - GBP
                    - HKD
                    - INR
                    - JPY
                    - KRW
                    - MXN
                    - NOK
                    - NZD
                    - PLN
                    - SEK
                    - SGD
                    - USD
                    - ZAR
              additionalProperties: false
            merchant_origin:
              type: string
            card:
              type: object
              required:
                - brand
                - token_last4
              properties:
                brand:
                  type: string
                token_last4:
                  type: string
              additionalProperties: false
            failure:
              type: string
              enum:
                - payment_total_over_limit
                - payment_total_mismatch
                - payment_method_no_token
                - payment_method_not_found
                - payment_declined
                - payment_approval_expired
                - payment_cancelled
                - payment_fill_failed
                - payment_vendor_unavailable
                - payment_interrupted
          additionalProperties: false
          description: >-
            A paying run's purchase, its newest when a retry made another:
            created, awaiting_cardholder while the cardholder's approval on the
            card network's page waits, ready, filled once the checkout has the
            payment method, then succeeded, declined (the store refused it),
            uncertain (the checkout had the payment method and the outcome is
            unknown, so it may have charged) or not_charged with its failure. No
            card data beyond the network token's last four
        shape:
          $ref: '#/components/schemas/JobShape'
        site_url:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            The website's https origin the job was asked for: a build's
            site_url, or the site of the tool a run runs
        site_name:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            The site's name: its tool's integration's; null until the job has a
            tool, such as a build that hasn't published yet
        task:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            A build's task, or a requested change, as it was sent; null for a
            run and a job accepted before Pomerado kept tasks
        tool_name:
          anyOf:
            - type: string
            - type: 'null'
          description: The name of the tool tool_id names, as GET /v1/tools shows it
        waiting_since:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            When the question input_request asks was asked; null when the job
            asks none
        answered_questions:
          type: array
          items:
            $ref: '#/components/schemas/JobAnsweredQuestion'
          description: >-
            The questions the job asked and its member answered, oldest first; a
            secret, login or code shows only that it was answered
        warnings:
          type: array
          items:
            $ref: '#/components/schemas/JobWarning'
          description: >-
            What to tell the person about a build or requested change, as is,
            or, on the answer that accepted a run, about its call. Absent when
            there is none
        started_by:
          type: object
          required:
            - member_id
          properties:
            member_id:
              type: string
              description: The member's user ID
          additionalProperties: false
          description: >-
            Who started the job. A Business team's Owners and Admins also read
            their teammates' jobs
        watch_url:
          type: string
        tip:
          type: string
        created_at:
          $ref: '#/components/schemas/Date'
        updated_at:
          $ref: '#/components/schemas/Date'
        completed_at:
          anyOf:
            - $ref: '#/components/schemas/Date'
            - type: 'null'
      additionalProperties: false
    job_id:
      type: string
      description: 'a job ID: job_ and 32 lowercase hex digits'
      examples:
        - job_0f8e2d1c4b3a49e8a7f6e5d4c3b2a190
    InputRequest:
      type: object
      required:
        - id
        - expires_at
        - answer_url
        - message
        - questions
      properties:
        id:
          type: string
          description: 'An input request ID: req_ and 32 lowercase hex digits'
          examples:
            - req_0f8e2d1c4b3a49e8a7f6e5d4c3b2a190
          pattern: ^req_[0-9a-f]{32}$
        expires_at:
          type: string
        answer_url:
          type: string
        message:
          type: string
        questions:
          type: array
          items:
            $ref: '#/components/schemas/Question'
        login_save:
          type: object
          required:
            - allowed
            - missing
            - grant_hint
          properties:
            allowed:
              type: boolean
              enum:
                - false
            missing:
              type: string
              enum:
                - logins:manage
              description: The permission the login's save would lack.
            grant_hint:
              type: string
              description: What to grant before the login is entered, so it is saved.
          additionalProperties: false
          description: >-
            Present when the login this job asks for would be used for this job
            only, because this client or the account role lacks logins:manage.
            grant_hint says what to grant to save it. Absent when the login can
            be saved.
      additionalProperties: false
    JobPause:
      type: object
      required:
        - reason
        - paused_at
        - expires_at
        - resume_by
      properties:
        reason:
          type: string
          enum:
            - question_expired
            - sign_in_expired
            - owner
            - credentials_rejected
        paused_at:
          $ref: '#/components/schemas/Date'
        expires_at:
          $ref: '#/components/schemas/Date'
        resume_by:
          type: string
          enum:
            - answer
            - resume
            - sign_in
      additionalProperties: false
    ResultFile:
      type: object
      required:
        - id
        - name
        - media_type
        - size
        - sha256
        - download_url
        - expires_at
      properties:
        id:
          type: string
        name:
          type: string
        media_type:
          type: string
        size:
          type: number
        sha256:
          type: string
        download_url:
          type: string
        transfer_key:
          type: string
          description: >-
            The link's transfer key: send it as the Pomerado-Transfer-Key header
            on the download. Given only to the API key, app or session that
            created the link.
        expires_at:
          type: string
      additionalProperties: false
    JobMaintenanceNow:
      type: object
      required:
        - label
        - started_at
      properties:
        label:
          type: string
          description: >-
            One line for the user saying what the repair is doing now, numbered
            as one of its 4 steps once it starts
        started_at:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            When the repair's current step started (ISO 8601 UTC); null when
            unknown
      additionalProperties: false
      description: >-
        What the repair is doing now while the run waits for it. Absent
        otherwise, and from an older backend
    JobMaintenanceInputRefusal:
      type: object
      required:
        - reason
      properties:
        reason:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            The tool's own reason for refusing the value. Null from a
            status-only read, or when Pomerado can't read it
      additionalProperties: false
      description: >-
        Present while the repair checks a value in the input that the tool
        refused. It finds whether the input or the tool is wrong. Absent
        otherwise, and from an older backend
    JobBuild:
      type: object
      required:
        - integration_id
        - stage
        - stages
        - eta
        - example_result
        - existing_tool_id
        - change
        - recorded
      properties:
        integration_id:
          anyOf:
            - $ref: '#/components/schemas/integration_id'
            - type: 'null'
        stage:
          type: string
          enum:
            - queued
            - checking_login
            - exploring
            - building
            - publishing
        stages:
          type: array
          items:
            type: object
            required:
              - key
              - label
              - status
              - started_at
              - completed_at
            properties:
              key:
                type: string
                enum:
                  - queued
                  - checking_login
                  - exploring
                  - building
                  - publishing
              label:
                type: string
              status:
                type: string
                enum:
                  - done
                  - active
                  - pending
              started_at:
                anyOf:
                  - type: string
                  - type: 'null'
              completed_at:
                anyOf:
                  - type: string
                  - type: 'null'
            additionalProperties: false
        now:
          anyOf:
            - $ref: '#/components/schemas/JobBuildNow'
            - type: 'null'
          description: What the build is doing now; null once it has ended
        eta:
          type: 'null'
          description: >-
            No longer provided: always null. Pomerado doesn't estimate how long
            a build takes
        example_result:
          $id: /schemas/unknown
        existing_tool_id:
          anyOf:
            - type: string
            - type: 'null'
        change:
          anyOf:
            - $ref: '#/components/schemas/JobChange'
            - type: 'null'
        recorded:
          type: boolean
          description: >-
            Whether the build's browser was recorded. A Business account watches
            the recording on the build page, or reads there why it was removed
        exploration:
          $ref: '#/components/schemas/JobBuildExploration'
      additionalProperties: false
    JobShape:
      type: object
      required:
        - id
        - version
        - status
      properties:
        id:
          type: string
        version:
          type: number
        status:
          type: string
          enum:
            - applied
            - skipped
        reason:
          type: string
          enum:
            - error
            - budget
            - output_mismatch
            - too_large
            - refusal_passthrough
            - branch_passthrough
        new_fields:
          type: array
          items:
            type: string
        message:
          type: string
      additionalProperties: false
      description: >-
        A run that named one of your shapes: what it did. applied: the result is
        in the shape's form, paging fields copied on. skipped: the result is the
        tool's own, and reason says why. new_fields: fields the tool returns now
        that the shape leaves out. message says why it was skipped and how to
        add new fields
    JobAnsweredQuestion:
      type: object
      required:
        - request_id
        - question_id
        - type
        - prompt
        - options
        - selected
        - other
        - note
        - text
        - confirmed
        - answered
        - value_hidden
        - asked_at
        - answered_at
      properties:
        request_id:
          type: string
        question_id:
          type: string
        type:
          type: string
        prompt:
          type: string
        options:
          anyOf:
            - type: array
              items:
                type: string
            - type: 'null'
          description: The offered options' labels, for a choice; null otherwise
        selected:
          type: array
          items:
            type: string
          description: The labels picked
        other:
          anyOf:
            - type: string
            - type: 'null'
          description: The member's own answer instead of, or beside, the offered options
        note:
          anyOf:
            - type: string
            - type: 'null'
        text:
          anyOf:
            - type: string
            - type: 'null'
          description: A text answer, or the text a confirmation sent
        confirmed:
          anyOf:
            - type: boolean
            - type: 'null'
        answered:
          type: boolean
          description: False for an optional question left unanswered
        value_hidden:
          type: boolean
          description: >-
            True for a secret, a login, a code, a saved login's choice or a
            phone number a sign-in asked for: it was answered, and its value is
            never shown
        asked_at:
          anyOf:
            - type: string
            - type: 'null'
        answered_at:
          anyOf:
            - type: string
            - type: 'null'
      additionalProperties: false
    JobWarning:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          enum:
            - non_us_site
            - extreme_test_mode
            - login_not_needed
        message:
          type: string
      additionalProperties: false
    Question:
      anyOf:
        - type: object
          required:
            - id
            - prompt
            - type
            - options
            - allow_other
            - allow_note
            - recommended
          properties:
            id:
              type: string
            prompt:
              type: string
            type:
              type: string
              enum:
                - choice
            options:
              type: array
              items:
                type: object
                required:
                  - id
                  - label
                properties:
                  id:
                    type: string
                  label:
                    type: string
                additionalProperties: false
            allow_other:
              type: boolean
            allow_note:
              type: boolean
            recommended:
              anyOf:
                - type: string
                - type: 'null'
              description: >-
                The answer the asker recommends, or null. A question left
                unanswered may go on with it.
          additionalProperties: false
        - type: object
          required:
            - id
            - prompt
            - type
            - options
            - min_selections
            - max_selections
            - allow_other
            - allow_note
            - recommended
          properties:
            id:
              type: string
            prompt:
              type: string
            type:
              type: string
              enum:
                - multi_choice
            options:
              type: array
              items:
                type: object
                required:
                  - id
                  - label
                properties:
                  id:
                    type: string
                  label:
                    type: string
                additionalProperties: false
            min_selections:
              $ref: '#/components/schemas/Int'
            max_selections:
              $ref: '#/components/schemas/Int'
            allow_other:
              type: boolean
            allow_note:
              type: boolean
            recommended:
              anyOf:
                - type: array
                  items:
                    type: string
                - type: 'null'
              description: >-
                The answer the asker recommends, or null. A question left
                unanswered may go on with it.
          additionalProperties: false
        - type: object
          required:
            - id
            - prompt
            - type
            - max_length
            - recommended
          properties:
            id:
              type: string
            prompt:
              type: string
            type:
              type: string
              enum:
                - text
            max_length:
              anyOf:
                - $ref: '#/components/schemas/Int'
                - type: 'null'
            recommended:
              anyOf:
                - type: string
                - type: 'null'
              description: >-
                The answer the asker recommends, or null. A question left
                unanswered may go on with it.
          additionalProperties: false
        - type: object
          required:
            - id
            - prompt
            - type
            - follow_up
          properties:
            id:
              type: string
            prompt:
              type: string
            type:
              type: string
              enum:
                - confirm
            follow_up:
              anyOf:
                - type: object
                  required:
                    - prompt
                  properties:
                    prompt:
                      type: string
                  additionalProperties: false
                - type: 'null'
          additionalProperties: false
        - type: object
          required:
            - id
            - prompt
            - type
            - kind
          properties:
            id:
              type: string
            prompt:
              type: string
            type:
              type: string
              enum:
                - secret
            kind:
              type: string
              enum:
                - one_time_code
                - authenticator_code
                - private_text
          additionalProperties: false
        - type: object
          required:
            - id
            - prompt
            - type
            - site_url
            - fields
            - reason
            - username_masked
            - can_save
          properties:
            id:
              type: string
            prompt:
              type: string
            type:
              type: string
              enum:
                - login
            site_url:
              type: string
            fields:
              type: array
              items:
                type: string
                enum:
                  - username
                  - email
                  - phone
                  - account_number
                  - password
            reason:
              type: string
              enum:
                - missing
                - rejected
                - expired
            username_masked:
              anyOf:
                - type: string
                - type: 'null'
            can_save:
              type: boolean
          additionalProperties: false
        - type: object
          required:
            - id
            - prompt
            - type
            - show_inputs
          properties:
            id:
              type: string
            prompt:
              type: string
            type:
              type: string
              enum:
                - browser_handoff
            show_inputs:
              type: array
              items:
                type: string
          additionalProperties: false
    integration_id:
      type: string
      description: 'an integration ID: int_ and 32 lowercase hex digits'
      examples:
        - int_0f8e2d1c4b3a49e8a7f6e5d4c3b2a190
    JobBuildNow:
      type: object
      required:
        - label
        - started_at
      properties:
        label:
          type: string
          description: >-
            One line for the user saying what the build is doing now, such as
            its step on the site, a test round's progress or that it waits for
            an answer. It changes as the build moves on
        started_at:
          anyOf:
            - type: string
            - type: 'null'
          description: When this line started (ISO 8601 UTC); null when unknown
      additionalProperties: false
    JobChange:
      type: object
      required:
        - revision_id
        - previous_revision_id
        - write_started
      properties:
        revision_id:
          anyOf:
            - type: string
            - type: 'null'
        previous_revision_id:
          anyOf:
            - type: string
            - type: 'null'
        write_started:
          type: boolean
        items:
          type: array
          items:
            $ref: '#/components/schemas/JobChangeItem'
          description: >-
            Once the change published, each part of its request and whether the
            change did it, with why for a part it didn't do. Absent before it
            publishes, when its repair recorded none, and from an older backend
        already_satisfied_by:
          type: array
          items:
            type: string
          description: >-
            Present when Pomerado found the tool already does what the change
            asks and left it unchanged: the tool's fields that do it, each a
            dotted path from input or output, such as output.items.price. Absent
            otherwise, and from an older backend
        shape:
          type: object
          required:
            - id
            - name
          properties:
            id:
              type: string
            name:
              type: string
          additionalProperties: false
          description: >-
            Present when the change, or part of it, only reshaped what the tool
            returns: the shape Pomerado saved for you instead. With no tool
            change needed, the job succeeds with the tool unchanged and nothing
            is charged
      additionalProperties: false
    JobBuildExploration:
      type: object
      required:
        - status
        - rows_run
        - rows_planned
        - drafts_used
      properties:
        status:
          type: string
          enum:
            - awaiting_script
            - exploring
            - folding
            - verifying
            - publishing
            - incomplete
            - failed
            - published
        rows_run:
          type: integer
          description: The answer sets the host ran on practice drafts so far
        rows_planned:
          type: integer
          description: The answer sets it planned
        drafts_used:
          type: integer
          description: The practice drafts it saved on the account, at most five
      additionalProperties: false
      description: >-
        An extreme test-mode build's exploration of the form on practice drafts
        before it publishes; absent on every other build and before it starts
    JobChangeItem:
      type: object
      required:
        - item
        - status
      properties:
        item:
          type: string
          description: >-
            The part as the request names it, such as 2 or b, or 1 for a request
            that names no parts
        status:
          type: string
          enum:
            - done
            - not_done
        reason:
          type: string
          description: Why the change didn't do this part
      additionalProperties: false
  securitySchemes:
    bearer:
      type: http
      scheme: bearer

````

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