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

# Poll a SmartBrowse run



## OpenAPI

````yaml /openapi.yaml get /smartbrowse/runs/{id}
openapi: 3.1.0
info:
  title: webscrape.ai API
  version: '1.0'
  description: |
    The public webscrape.ai API. Fetch pages and get back structured JSON,
    HTML, markdown, or replayed browser output.

    Every response is wrapped in one of three envelope shapes —
    `completed`, `queued`, or `error`. Always check the top-level
    `status` first, then read `data` (success or queued) or `error`
    (failure).
  contact:
    name: webscrape.ai support
    email: hello@webscrape.ai
    url: https://webscrape.ai
servers:
  - url: https://api.webscrape.ai/v1
    description: Production
security:
  - ApiKeyAuth: []
tags:
  - name: Scrape
    description: Raw fetching and structured extraction.
  - name: SmartBrowse
    description: Real-Chrome recipe replay with pagination and interactions.
paths:
  /smartbrowse/runs/{id}:
    get:
      tags:
        - SmartBrowse
      summary: Poll a SmartBrowse run
      operationId: getSmartBrowseRun
      parameters:
        - name: id
          in: path
          required: true
          description: Opaque run ID (~11 base62 chars).
          schema:
            type: string
            example: k7Xb9dRmQ2p
      responses:
        '200':
          description: Run state returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SmartBrowseRunSuccess'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  schemas:
    SmartBrowseRunSuccess:
      allOf:
        - $ref: '#/components/schemas/EnvelopeBase'
        - type: object
          required:
            - data
            - credits_used
            - credits_remaining
          properties:
            status:
              type: string
              enum:
                - completed
            data:
              $ref: '#/components/schemas/SmartBrowseRunData'
            credits_used:
              type: integer
              description: >-
                Always 0. Polling is free; the run's accrued credits are
                surfaced in `data.credits_used`.
              example: 0
            credits_remaining:
              type: integer
    EnvelopeBase:
      type: object
      required:
        - status
        - request_id
      properties:
        status:
          type: string
          enum:
            - completed
            - queued
            - error
          description: Discriminator for the envelope variant.
        request_id:
          type: string
          example: req_aB3xY9Kp
          description: |
            Per-request id. Also returned as the `X-Request-ID` response
            header. Include it when reporting issues.
    SmartBrowseRunData:
      type: object
      required:
        - id
        - recipe_id
        - run_status
        - pages_extracted
        - items_extracted
        - credits_used
        - created_at
      properties:
        id:
          type: string
          example: k7Xb9dRmQ2p
          description: Opaque run ID (~11 base62 chars).
        recipe_id:
          type: string
          example: m3Yc2tFvN8q
          description: Opaque recipe ID (~11 base62 chars).
        run_status:
          $ref: '#/components/schemas/SmartBrowseRunStatus'
        pages_extracted:
          type: integer
        items_extracted:
          type: integer
        credits_used:
          type: integer
        started_at:
          type:
            - string
            - 'null'
          format: date-time
        completed_at:
          type:
            - string
            - 'null'
          format: date-time
        error:
          type: string
          description: Set only on `failed` / `cancelled` runs. Omitted otherwise.
        result:
          type: object
          description: Present once `run_status` is `completed`. Omitted while running.
          properties:
            pages:
              type: array
              items:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      type: object
                      additionalProperties: true
            mode:
              type: string
            drift:
              type: number
            warnings:
              type: array
              items:
                type: string
        created_at:
          type: string
          format: date-time
    EnvelopeError:
      allOf:
        - $ref: '#/components/schemas/EnvelopeBase'
        - type: object
          required:
            - error
          properties:
            status:
              type: string
              enum:
                - error
            error:
              type: object
              required:
                - code
                - message
              properties:
                code:
                  $ref: '#/components/schemas/ErrorCode'
                message:
                  type: string
                  description: >-
                    Human-readable. May change between releases. Log it; don't
                    pattern-match.
                details:
                  description: >-
                    Optional structured context (e.g. `{balance, required}` for
                    `insufficient_credits`).
    SmartBrowseRunStatus:
      type: string
      enum:
        - queued
        - running
        - completed
        - failed
        - cancelled
      description: |
        Run lifecycle state. Renamed from `status` to avoid colliding
        with the envelope's outer `status`. `cancelled` appears when the
        run was force-stopped (e.g. account deletion confirmed while a
        run was in flight); `failed` covers everything else terminal.
    ErrorCode:
      type: string
      description: Stable error code. SDKs branch on this.
      enum:
        - invalid_request
        - unauthorized
        - insufficient_credits
        - email_verification_required
        - forbidden
        - not_found
        - conflict
        - account_deletion_pending
        - validation_failed
        - rate_limited
        - internal_error
        - service_unavailable
  responses:
    Unauthorized:
      description: Missing, invalid, or revoked API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/EnvelopeError'
          example:
            status: error
            error:
              code: unauthorized
              message: missing or invalid credentials
            request_id: req_aB3xY9Kp
    NotFound:
      description: Resource does not exist or belongs to another user.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/EnvelopeError'
          example:
            status: error
            error:
              code: not_found
              message: recipe not found
            request_id: req_aB3xY9Kp
    InternalError:
      description: Internal server error. Safe to retry with backoff.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/EnvelopeError'
          example:
            status: error
            error:
              code: internal_error
              message: internal error
            request_id: req_aB3xY9Kp
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: |
        Generate from the [dashboard](https://webscrape.ai/app/api-keys).
        Format: `wsg_live_<32 base62 chars>`.

````