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

# POST /batch/{endpoint}

> Run brand, enrich, company, classify, screenshot or styleguide on up to 500 URLs as one job. Free to submit.

Starts a batch of one endpoint and returns `202` with a job id. Read results with [`GET /batch/{endpoint}/{id}`](https://docs.prefetch.io/api-reference/endpoint/batch-status).

**Free to submit.** Each URL answered costs what one call of that endpoint costs. Failed requests are never charged.

> [card] [Guide: Batches](https://docs.prefetch.io/jobs/batches.md)
>
> Options, results, webhooks, credits and examples.


## OpenAPI

````yaml POST /batch/{endpoint}
openapi: 3.1.0
info:
  title: Prefetch API
  description: >-
    Extract brand identity, company data, screenshots, IAB classifications, and
    clean page content from any URL.
  version: 1.0.0
  contact:
    email: support@prefetch.io
servers:
  - url: https://api.prefetch.io
    description: Production
security:
  - apiKey: []
tags:
  - name: Endpoints
    description: Data extraction endpoints. All require authentication and consume credits.
  - name: Health
    description: Health and readiness probes. No authentication required.
paths:
  /batch/{endpoint}:
    post:
      tags:
        - Endpoints
      summary: Run an endpoint on many URLs
      description: >-
        Runs `brand`, `enrich`, `company`, `classify`, `screenshot` or
        `styleguide` on up to 500 URLs or bare domains as one job, and returns
        its id immediately. Each URL is answered exactly as `GET /{endpoint}`
        would answer it — curated data first, then a live extraction — with
        `options` (that endpoint's own parameters) applied to every URL. Poll
        `GET /batch/{endpoint}/{id}` for progress and results, or pass a
        `webhook`: events are named `batch_{endpoint}.*` (`batch_enrich.page`
        per URL, `batch_enrich.completed` at the end).


        **Credit cost: nothing to submit, then the endpoint's own price per URL
        answered** (enrich 12, brand 10, styleguide 10, classify 5, company 5,
        screenshot 1). URLs that fail are never charged. A key whose balance
        cannot cover every URL is refused up front with `CREDITS_EXHAUSTED`.
        Webhooks are not available through RapidAPI.
      operationId: createBatch
      parameters:
        - schema:
            type: string
            enum:
              - brand
              - enrich
              - company
              - classify
              - screenshot
              - styleguide
            description: What every URL is run through. /batch/scrape has its own page.
            example: enrich
          required: true
          description: What every URL is run through. /batch/scrape has its own page.
          name: endpoint
          in: path
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchBody'
      responses:
        '202':
          description: Batch queued.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/BatchJobData'
                  meta:
                    $ref: '#/components/schemas/Meta'
                required:
                  - success
                  - data
                  - meta
              example:
                success: true
                data:
                  id: crw_7c2e9a4b1d0f4e6a8b3c5d7e9f1a2b3c
                  status: pending
                  endpoint: enrich
                  url_count: 3
                  invalid_urls: []
                  created_at: '2026-10-13T09:14:03.221Z'
                  expires_at: '2026-10-14T09:14:03.221Z'
                meta:
                  requestId: 6f1d2c3b-4a5e-4f60-8b7a-9c0d1e2f3a4b
                  durationMs: 1840
        '400':
          description: Invalid or missing parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Revoked key, expired key, blocked URL, or credit limit.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate or concurrency limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service temporarily unavailable — retry shortly.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    BatchBody:
      type: object
      properties:
        urls:
          type: array
          items:
            type: string
          description: >-
            The URLs or bare domains to run (1–500). Duplicates run once.
            `domains` is accepted too.
          example:
            - stripe.com
            - https://linear.app
            - notion.so
        options:
          type: object
          additionalProperties:
            nullable: true
          description: >-
            The endpoint's own parameters, as GET /{endpoint} takes them,
            applied to every URL — e.g. `{"design_tokens": true}` for brand or
            enrich, `{"device": "iphone_15"}` for screenshot. Typed JSON or
            strings.
          example:
            design_tokens: true
        concurrency:
          type: integer
          description: >-
            URLs run in parallel (1–5). Default: 2. Batches of brand, enrich,
            screenshot and styleguide run at most 3 at a time, and default to 3.
        ignore_invalid_urls:
          type: boolean
          description: >-
            Drop URLs that fail validation (listed in `invalid_urls`) instead of
            rejecting the whole batch. Default: false.
        webhook:
          $ref: '#/components/schemas/CrawlWebhook'
      required:
        - urls
    BatchJobData:
      type: object
      properties:
        id:
          type: string
          example: crw_4b1e9c0a7d2f4e6b
        endpoint:
          type: string
          description: What each URL is run through.
          example: scrape
        status:
          type: string
          enum:
            - pending
            - running
            - completed
            - failed
            - cancelled
        url_count:
          type: integer
          description: >-
            Pages queued, after removing duplicates (and invalid URLs, with
            ignore_invalid_urls).
        invalid_urls:
          type: array
          items:
            type: string
          description: URLs dropped by ignore_invalid_urls.
        created_at:
          type: string
          format: date-time
        expires_at:
          type: string
          format: date-time
        webhook:
          type: object
          description: Present when the request set `webhook`.
          properties:
            url:
              type: string
            events:
              type: array
              items:
                type: string
            secret:
              type: string
              description: >-
                Verifies the `X-Prefetch-Signature` on each delivery. Shown only
                here — store it.
      required:
        - id
        - status
        - url_count
        - invalid_urls
        - created_at
        - expires_at
    Meta:
      type: object
      properties:
        requestId:
          type: string
          format: uuid
          description: Unique identifier for this request.
          example: a3f2c1d4-7b6e-4f2a-9c1d-8e3f2a1b4c5d
        durationMs:
          type: integer
          nullable: true
          description: Time taken to process the request in milliseconds.
          example: 1842
      required:
        - requestId
        - durationMs
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          enum:
            - false
          description: >-
            Always false. Absent, like `meta`, on authentication and rate-limit
            errors, which are answered before a request is processed.
        error:
          type: string
          description: >-
            Human-readable error message. The wording can change: branch on
            `error_code`.
          example: Credit limit exceeded
        error_code:
          type: string
          enum:
            - INVALID_REQUEST
            - PAYLOAD_TOO_LARGE
            - NOT_FOUND
            - CONFLICT
            - UNAUTHORIZED
            - FORBIDDEN
            - CREDITS_EXHAUSTED
            - RATE_LIMITED
            - CONCURRENCY_LIMITED
            - URL_BLOCKED
            - URL_NOT_PERMITTED
            - DNS_RESOLUTION_FAILED
            - TARGET_BLOCKED
            - TARGET_CONNECTION_FAILED
            - TARGET_TIMEOUT
            - TARGET_SSL_ERROR
            - TARGET_SERVER_ERROR
            - TARGET_CLIENT_ERROR
            - TARGET_NOT_A_PAGE
            - NO_LINKS_FOUND
            - TARGET_UNLOADABLE
            - RESEARCH_INCONCLUSIVE
            - TIMEOUT
            - SERVICE_BUSY
            - SERVICE_UNAVAILABLE
            - INTERNAL_ERROR
          description: >-
            What went wrong, for machines. Stable: a code keeps its meaning once
            published. See [Error handling](/concepts/errors).
          example: CREDITS_EXHAUSTED
        retryable:
          type: boolean
          description: >-
            Whether the same request can succeed if sent again after a short
            wait (honour `Retry-After` when present). False for problems with
            the request or the target.
          example: false
        retryAfterSeconds:
          type: integer
          description: 'On `RATE_LIMITED`: seconds until a request will be accepted.'
        limit:
          type: integer
          description: >-
            On `CONCURRENCY_LIMITED`: how many requests this key may have in
            flight.
        meta:
          $ref: '#/components/schemas/Meta'
      required:
        - error
        - error_code
        - retryable
    CrawlWebhook:
      anyOf:
        - type: string
          description: An https:// URL; every event is sent.
        - type: object
          properties:
            url:
              type: string
              example: https://example.com/hooks/prefetch
            events:
              type: array
              items:
                type: string
                enum:
                  - started
                  - page
                  - completed
                  - failed
              description: 'Which events to send. Default: all four.'
            headers:
              type: object
              additionalProperties:
                type: string
              description: Sent with every delivery (up to 20).
            metadata:
              type: object
              additionalProperties:
                nullable: true
              description: Echoed back in every payload (up to 4 KB).
          required:
            - url
      description: >-
        Where to send progress. Each delivery is signed — `X-Prefetch-Signature:
        t=<unix>,v1=<hex>`, HMAC-SHA256 of `<t>.<raw body>` with the `secret`
        returned when the job is created — the same scheme as monitor webhooks.
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: Your Prefetch API key. Obtain one from the dashboard.

````

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