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

# Run Extract

> Fill in your JSON Schema with data from a completed parse. Send the parse's `parse_id` with `config` or a saved `config_id`. By default, the call waits for the job to end. With `async: true`, it returns `202` at once. Read the data at `GET /extract/{extract_id}/result`.



## OpenAPI

````yaml /api-reference/v2/openapi.yml post /extract
openapi: 3.1.0
info:
  title: Pulse API
  description: >-
    Agentic document infrastructure for the enterprise. The Pulse API turns
    complex documents into AI-ready data, such as Markdown, structured JSON and
    bounding boxes.
  version: '2'
servers:
  - url: https://api.runpulse.com
    description: Default Pulse API base URL
security: []
tags:
  - name: Parse
    description: Parse a document's text, tables and figures.
  - name: Batch parse
    description: Parse many documents with one config.
  - name: Extract
    description: Extract structured data from a parsed document.
  - name: Split
    description: Find each topic's pages in a parsed document.
  - name: Tables
    description: Merge a parsed document's tables across pages.
  - name: Charts
    description: Read the charts in a parsed document.
  - name: Classify
    description: Sort a document into the categories you define.
  - name: Pipeline
    description: Run a parse and its follow-on steps as one job.
  - name: Usage
    description: Check the pages and credits your organization has used.
  - name: Webhook
    description: Get notified when your organization's jobs change status.
  - name: Organization settings
    description: Read and change your organization's name, address and default API version.
paths:
  /extract:
    post:
      tags:
        - Extract
      summary: Run Extract
      description: >-
        Fill in your JSON Schema with data from a completed parse. Send the
        parse's `parse_id` with `config` or a saved `config_id`. By default, the
        call waits for the job to end. With `async: true`, it returns `202` at
        once. Read the data at `GET /extract/{extract_id}/result`.
      operationId: extractDocument
      parameters:
        - name: Pulse-Version
          in: header
          required: false
          schema:
            type: string
            default: '2'
            title: Pulse-Version
          examples:
            default:
              value: '2'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              description: >-
                A completed parse to extract from, and the options to extract
                with.
              title: ExtractRequest
              oneOf:
                - title: Inline config
                  additionalProperties: false
                  type: object
                  properties:
                    parse_id:
                      description: >-
                        The `parse_id` of a completed parse whose result hasn't
                        expired.
                      minLength: 1
                      title: Parse Id
                      type: string
                    async:
                      default: false
                      description: >-
                        Set to `true` to return `202` at once instead of
                        waiting.
                      title: Async
                      type: boolean
                    config:
                      $ref: '#/components/schemas/ExtractConfig'
                      description: This request's options.
                  required:
                    - parse_id
                    - config
                - title: Saved config
                  additionalProperties: false
                  type: object
                  properties:
                    parse_id:
                      description: >-
                        The `parse_id` of a completed parse whose result hasn't
                        expired.
                      minLength: 1
                      title: Parse Id
                      type: string
                    async:
                      default: false
                      description: >-
                        Set to `true` to return `202` at once instead of
                        waiting.
                      title: Async
                      type: boolean
                    config_id:
                      description: A saved config's id, sent in place of `config`.
                      title: Config Id
                      type: string
                  required:
                    - parse_id
                    - config_id
      responses:
        '200':
          description: >-
            The extraction completed. Read its data at `GET
            /extract/{extract_id}/result`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExtractSyncResponse'
        '202':
          description: >-
            The extraction started (`async: true`). Check `GET
            /extract/{extract_id}` until it ends.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExtractAsyncResponse'
        '400':
          description: >-
            The body or query is invalid
            ([`REQUEST_INVALID`](https://docs.runpulse.com/errors/request-invalid));
            `parse_id` names a parse this endpoint can't read
            ([`RESOURCE_UNUSABLE`](https://docs.runpulse.com/errors/resource-unusable);
            `reason` says why); or `config.page_range` extends past the parse's
            pages
            ([`PAGE_RANGE_INVALID`](https://docs.runpulse.com/errors/page-range-invalid)).
            `Pulse-Version` names a version this API doesn't serve
            ([`UNSUPPORTED_VERSION`](https://docs.runpulse.com/errors/unsupported-version)).
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
          headers:
            X-Request-Id:
              description: The request's id; the problem's `request_id`.
              schema:
                type: string
          x-pulse-errors:
            - REQUEST_INVALID
            - RESOURCE_UNUSABLE
            - PAGE_RANGE_INVALID
            - UNSUPPORTED_VERSION
        '401':
          description: >-
            Your API key is missing or invalid
            ([`CREDENTIALS_INVALID`](https://docs.runpulse.com/errors/credentials-invalid)),
            or inactive
            ([`API_KEY_INACTIVE`](https://docs.runpulse.com/errors/api-key-inactive)).
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
          headers:
            X-Request-Id:
              description: The request's id; the problem's `request_id`.
              schema:
                type: string
          x-pulse-errors:
            - CREDENTIALS_INVALID
            - API_KEY_INACTIVE
        '402':
          description: >-
            Payment is required
            ([`PAYMENT_REQUIRED`](https://docs.runpulse.com/errors/payment-required)),
            failed
            ([`PAYMENT_FAILED`](https://docs.runpulse.com/errors/payment-failed)),
            needs authentication
            ([`PAYMENT_AUTHENTICATION_REQUIRED`](https://docs.runpulse.com/errors/payment-authentication-required)),
            or is past due
            ([`SUBSCRIPTION_PAST_DUE`](https://docs.runpulse.com/errors/subscription-past-due));
            your trial has expired
            ([`TRIAL_EXPIRED`](https://docs.runpulse.com/errors/trial-expired)),
            a credit limit is exceeded
            ([`CREDIT_LIMIT_EXCEEDED`](https://docs.runpulse.com/errors/credit-limit-exceeded)),
            your plan allows no more
            ([`PLAN_LIMIT_REACHED`](https://docs.runpulse.com/errors/plan-limit-reached)),
            or your subscription is canceled
            ([`SUBSCRIPTION_CANCELED`](https://docs.runpulse.com/errors/subscription-canceled)).
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
          headers:
            X-Request-Id:
              description: The request's id; the problem's `request_id`.
              schema:
                type: string
          x-pulse-errors:
            - PAYMENT_REQUIRED
            - PAYMENT_FAILED
            - PAYMENT_AUTHENTICATION_REQUIRED
            - SUBSCRIPTION_PAST_DUE
            - TRIAL_EXPIRED
            - CREDIT_LIMIT_EXCEEDED
            - PLAN_LIMIT_REACHED
            - SUBSCRIPTION_CANCELED
        '403':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
          description: >-
            Your account is suspended
            ([`ACCOUNT_SUSPENDED`](https://docs.runpulse.com/errors/account-suspended)).
          headers:
            X-Request-Id:
              description: The request's id; the problem's `request_id`.
              schema:
                type: string
          x-pulse-errors:
            - ACCOUNT_SUSPENDED
        '404':
          description: >-
            `parse_id` names no parse of yours, or `config_id` no saved
            extraction config
            ([`RESOURCE_NOT_FOUND`](https://docs.runpulse.com/errors/resource-not-found);
            `errors` names the field). No endpoint answers this path
            ([`ROUTE_NOT_FOUND`](https://docs.runpulse.com/errors/route-not-found)).
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
          headers:
            X-Request-Id:
              description: The request's id; the problem's `request_id`.
              schema:
                type: string
          x-pulse-errors:
            - RESOURCE_NOT_FOUND
            - ROUTE_NOT_FOUND
        '409':
          description: >-
            The extraction job was canceled before it completed
            ([`JOB_ALREADY_ENDED`](https://docs.runpulse.com/errors/job-already-ended));
            or its completion couldn't yet be confirmed, or `parse_id` names a
            parse that hasn't completed yet
            ([`JOB_NOT_FINISHED`](https://docs.runpulse.com/errors/job-not-finished)).
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
          headers:
            X-Request-Id:
              description: The request's id; the problem's `request_id`.
              schema:
                type: string
          x-pulse-errors:
            - JOB_ALREADY_ENDED
            - JOB_NOT_FINISHED
        '410':
          description: >-
            `parse_id` names a parse whose result has expired
            ([`RESULT_EXPIRED`](https://docs.runpulse.com/errors/result-expired)).
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
          headers:
            X-Request-Id:
              description: The request's id; the problem's `request_id`.
              schema:
                type: string
          x-pulse-errors:
            - RESULT_EXPIRED
        '422':
          description: >-
            The selected pages hold no text or figures
            ([`DOCUMENT_UNPROCESSABLE`](https://docs.runpulse.com/errors/document-unprocessable)).
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
          headers:
            X-Request-Id:
              description: The request's id; the problem's `request_id`.
              schema:
                type: string
          x-pulse-errors:
            - DOCUMENT_UNPROCESSABLE
        '500':
          description: >-
            Extraction processing failed
            ([`PROCESSING_FAILED`](https://docs.runpulse.com/errors/processing-failed)),
            or an unexpected error occurred
            ([`SERVER_ERROR`](https://docs.runpulse.com/errors/server-error)).
            [`JOB_UNREADABLE`](https://docs.runpulse.com/errors/job-unreadable):
            Pulse can't read this job right now; don't retry, contact support.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
          headers:
            X-Request-Id:
              description: The request's id; the problem's `request_id`.
              schema:
                type: string
          x-pulse-errors:
            - PROCESSING_FAILED
            - SERVER_ERROR
            - JOB_UNREADABLE
        '503':
          description: >-
            Extraction or a service the request needs is unavailable
            ([`SERVICE_UNAVAILABLE`](https://docs.runpulse.com/errors/service-unavailable));
            if the problem carries `extract_id`, poll that existing job.
            Extraction processing is at capacity
            ([`CAPACITY_EXCEEDED`](https://docs.runpulse.com/errors/capacity-exceeded));
            retry after the seconds in `Retry-After`. Your deployment's license
            may also be invalid or expired
            ([`LICENSE_INVALID`](https://docs.runpulse.com/errors/license-invalid)),
            or not activated
            ([`LICENSE_NOT_ACTIVATED`](https://docs.runpulse.com/errors/license-not-activated)).
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
          headers:
            X-Request-Id:
              description: The request's id; the problem's `request_id`.
              schema:
                type: string
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: string
          x-pulse-errors:
            - SERVICE_UNAVAILABLE
            - CAPACITY_EXCEEDED
            - LICENSE_INVALID
            - LICENSE_NOT_ACTIVATED
      security:
        - ApiKey: []
components:
  schemas:
    ExtractConfig:
      additionalProperties: false
      description: Options for extracting structured data from a completed parse.
      properties:
        page_range:
          description: >-
            The pages to read, listed as numbers and ranges from 1, such as
            `1-3, 6, 8-end` (`end` is the last page). Defaults to every page.
            Pages are numbered as in the parse's result.
          pattern: ^ *[0-9]+ *(- *([0-9]+|end) *)?(, *[0-9]+ *(- *([0-9]+|end) *)?)*$
          title: Page Range
          type: string
        prompt:
          description: Extra instructions for filling in `input_schema`.
          minLength: 1
          title: Prompt
          type: string
        input_schema:
          additionalProperties:
            $ref: '#/components/schemas/JsonValue'
          description: >-
            The JSON Schema (Draft 7) to fill in, with an object root, at least
            one property and at most 5,000 properties in all.
          title: Input Schema
          type: object
        effort:
          default: low
          description: '`high` reads the parse more carefully, at an extra charge per page.'
          enum:
            - low
            - high
          title: Effort
          type: string
        confidence:
          default: standard
          description: >-
            `agentic` gives more reliable confidence scores, at an extra charge
            per page. It must be enabled for your organization.
          enum:
            - standard
            - agentic
          title: Confidence
          type: string
        format:
          anyOf:
            - const: all
              type: string
            - items:
                enum:
                  - enriched
                  - raw
                type: string
              type: array
          default:
            - enriched
          description: >-
            `enriched` returns values with citations and confidence, `raw`
            returns the values alone, and `all` returns both.
          title: Format
      required:
        - input_schema
      title: ExtractConfig { page_range, prompt, input_schema, 3 more }
      type: object
    ExtractSyncResponse:
      properties:
        extract_id:
          type: string
          title: Extract Id
          description: The extraction's id, `extract-<uuid>`.
        created_at:
          type: string
          title: Created At
          description: When the job was created.
        completed_at:
          type: string
          title: Completed At
          description: When the job ended.
        expires_at:
          type: string
          title: Expires At
          description: >-
            When the result will be deleted. Absent when the result is kept with
            no expiry.
      additionalProperties: false
      type: object
      required:
        - extract_id
        - created_at
        - completed_at
      title: ExtractSyncResponse
      description: >-
        A completed extraction. Read its data at `GET
        /extract/{extract_id}/result`.
    ExtractAsyncResponse:
      properties:
        extract_id:
          type: string
          title: Extract Id
          description: The extraction's id, `extract-<uuid>`.
        created_at:
          type: string
          title: Created At
          description: When the job was created.
      additionalProperties: false
      type: object
      required:
        - extract_id
        - created_at
      title: ExtractAsyncResponse
      description: >-
        An extraction that has started. Check `GET /extract/{extract_id}` until
        it ends.
    Problem:
      additionalProperties: false
      description: >-
        Why the request or the job failed. Branch on `code`; quote `request_id`
        to support.
      properties:
        type:
          description: 'This code''s page: what it means and what to do.'
          title: Type
          type: string
        title:
          description: A short summary of the code, the same for every occurrence.
          title: Title
          type: string
        status:
          description: The HTTP status the code answers with.
          title: Status
          type: integer
        detail:
          description: What happened this time.
          title: Detail
          type: string
        instance:
          description: 'This occurrence: the request''s URN, `urn:pulse:request:<id>`.'
          title: Instance
          type: string
        code:
          description: The stable error code, e.g. `REQUEST_INVALID`. Branch on it.
          title: Code
          type: string
        request_id:
          description: >-
            The request that failed, as `X-Request-Id` named it; for a failed
            job, the request that created it. Quote it to support.
          title: Request Id
          type: string
        retryable:
          description: Whether the same request may succeed if sent again.
          title: Retryable
          type: boolean
        retry_after:
          description: Seconds to wait before retrying, as `Retry-After` says.
          title: Retry After
          type: integer
        errors:
          description: Each refused part of the request.
          items:
            $ref: '#/components/schemas/FieldIssue'
          title: Errors
          type: array
        resource:
          description: 'What wasn''t found: `job`, `batch`, `webhook`, `config`, …'
          title: Resource
          type: string
        reason:
          description: The cause within the code.
          title: Reason
          type: string
        parse_id:
          description: The parse the request recorded.
          title: Parse Id
          type: string
        extract_id:
          description: The extraction it recorded.
          title: Extract Id
          type: string
        split_id:
          description: The split it recorded.
          title: Split Id
          type: string
        classify_id:
          description: The classification it recorded.
          title: Classify Id
          type: string
        tables_id:
          description: The tables job it recorded.
          title: Tables Id
          type: string
        charts_id:
          description: The charts job it recorded.
          title: Charts Id
          type: string
        pipeline_id:
          description: The pipeline it recorded.
          title: Pipeline Id
          type: string
        batch_id:
          description: The batch it recorded.
          title: Batch Id
          type: string
        filename:
          description: The file refused.
          title: Filename
          type: string
        declared_type:
          description: The type its name declared.
          title: Declared Type
          type: string
        detected:
          description: The type its contents are.
          title: Detected
          type: string
        supported_types:
          description: The types accepted.
          items:
            type: string
          title: Supported Types
          type: array
        supported:
          description: The values accepted.
          items:
            type: string
          title: Supported
          type: array
        max_size_mb:
          anyOf:
            - type: integer
            - type: number
          description: The largest size accepted.
          title: Max Size Mb
        file_size_mb:
          anyOf:
            - type: integer
            - type: number
          description: The file's size.
          title: File Size Mb
        plan_name:
          description: Your organization's plan.
          title: Plan Name
          type: string
        pages_used:
          anyOf:
            - type: integer
            - type: number
          description: Pages used this period.
          title: Pages Used
        page_allowance:
          anyOf:
            - type: integer
            - type: number
          description: Pages the plan allows.
          title: Page Allowance
        upgrade_url:
          description: Where to change your plan.
          title: Upgrade Url
          type: string
        action_required:
          description: What to do to continue.
          title: Action Required
          type: string
        billing_info:
          additionalProperties:
            $ref: '#/components/schemas/JsonValue'
          description: Your organization's billing state, as the gate read it.
          title: Billing Info
          type: object
      required:
        - type
        - title
        - status
        - code
        - retryable
      title: Problem
      type: object
    JsonValue: {}
    FieldIssue:
      additionalProperties: false
      description: One refused part of the request.
      properties:
        field:
          description: >-
            The part as sent: a body field's path
            (`config.enhancements.detect[1]`), or `query.<name>` /
            `header.<name>`.
          title: Field
          type: string
        pointer:
          description: >-
            A body field as a JSON Pointer (RFC 6901), e.g.
            `#/config/enhancements/detect/1`. Absent for a query parameter or
            header.
          title: Pointer
          type: string
        issue:
          description: What is wrong with it.
          title: Issue
          type: string
      required:
        - field
        - issue
      title: FieldIssue
      type: object
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: x-api-key

````

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