> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.cloudraker.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.cloudraker.com/_mcp/server.

# Extract from many files in one call

POST https://api.cloudraker.com/v1/extract/batch
Content-Type: application/json

Runs one saved extraction action over up to 100 files, creating one ordinary run per file.

A batch is fan-out sugar, not a new object: there is no batch id and nothing to poll for the batch as a whole. You get back a run id per file — read each one with [GET /v1/runs/{id}](https://docs.cloudraker.com/api/cloud-raker-api/runs/get-run), or list them together with [GET /v1/runs](https://docs.cloudraker.com/api/cloud-raker-api/runs/list-runs) using the `metadata` you attached.

**A saved `action` is required.** Inline `schema` and `hints` are accepted on [POST /v1/extract](https://docs.cloudraker.com/api/cloud-raker-api/capabilities/extract) only — running the same shape over a hundred files is exactly when that shape should be a reviewed, saved asset.

`metadata`, `webhook` and `ttl` are copied onto every run, so one webhook endpoint receives all of them.

```json
{
  "action": "invoice-fields",
  "files": [{ "id": "a04d6597-…" }, { "url": "https://example.com/invoice-2.pdf" }],
  "metadata": { "batch": "2026-07-25-invoices" }
}
```

**Always asynchronous.** The response is `202` right away. `runs[]` has one entry per file, in the order you sent them: `{id, statusUrl, file}` when the run was created, or `{file, error}` when that one file could not start — the other runs still stand, and `count` reports how many were created.

<Note>
The whole batch costs a single request against your rate limit, however many files it fans out to.
</Note>

**Learn more:** [Extraction guide](https://docs.cloudraker.com/capabilities/extract)

Reference: https://docs.cloudraker.com/api/cloud-raker-api/capabilities/extract-batch

## OpenAPI Specification

```yaml
openapi: 3.1.0
info:
  title: CloudRaker API
  version: 1.0.0
paths:
  /v1/extract/batch:
    post:
      operationId: extract-batch
      summary: Extract from many files in one call
      description: >-
        Runs one saved extraction action over up to 100 files, creating one
        ordinary run per file.


        A batch is fan-out sugar, not a new object: there is no batch id and
        nothing to poll for the batch as a whole. You get back a run id per file
        — read each one with [GET
        /v1/runs/{id}](https://docs.cloudraker.com/api/cloud-raker-api/runs/get-run),
        or list them together with [GET
        /v1/runs](https://docs.cloudraker.com/api/cloud-raker-api/runs/list-runs)
        using the `metadata` you attached.


        **A saved `action` is required.** Inline `schema` and `hints` are
        accepted on [POST
        /v1/extract](https://docs.cloudraker.com/api/cloud-raker-api/capabilities/extract)
        only — running the same shape over a hundred files is exactly when that
        shape should be a reviewed, saved asset.


        `metadata`, `webhook` and `ttl` are copied onto every run, so one
        webhook endpoint receives all of them.


        ```json

        {
          "action": "invoice-fields",
          "files": [{ "id": "a04d6597-…" }, { "url": "https://example.com/invoice-2.pdf" }],
          "metadata": { "batch": "2026-07-25-invoices" }
        }

        ```


        **Always asynchronous.** The response is `202` right away. `runs[]` has
        one entry per file, in the order you sent them: `{id, statusUrl, file}`
        when the run was created, or `{file, error}` when that one file could
        not start — the other runs still stand, and `count` reports how many
        were created.


        <Note>

        The whole batch costs a single request against your rate limit, however
        many files it fans out to.

        </Note>


        **Learn more:** [Extraction
        guide](https://docs.cloudraker.com/capabilities/extract)
      tags:
        - ''
      parameters:
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      responses:
        '202':
          description: Accepted — one run per file.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V1ExtractBatchAccepted'
        '400':
          description: Invalid request (`invalid_request`).
          content:
            application/json:
              schema:
                description: Any type
        '422':
          description: Unusable webhook endpoint.
          content:
            application/json:
              schema:
                description: Any type
        '429':
          description: >-
            Rate limited. The `/v1` API allows at least **67 requests per minute
            per organization** (about 1,000 requests per 15 minutes) — a
            guaranteed floor, enforced per edge location, so a geographically
            spread caller may get more. Wait for the `Retry-After` interval and
            retry — the error is `retryable`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExtractBatchRequestTooManyRequestsError'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V1ExtractBatchBody'
servers:
  - url: https://api.cloudraker.com
    description: Production
  - url: https://api.staging.raker.one
    description: Staging
  - url: https://api.dev.raker.one
    description: Development
components:
  schemas:
    V1ExtractBatchBodyFilesItemsOneOf0Processing:
      type: string
      enum:
        - auto
        - ocr
        - simple
        - transcribe
        - transcribe_diarize
      title: V1ExtractBatchBodyFilesItemsOneOf0Processing
    V1ExtractBatchBodyFilesItems0:
      type: object
      properties:
        url:
          type: string
          format: uri
        name:
          type: string
        processing:
          $ref: '#/components/schemas/V1ExtractBatchBodyFilesItemsOneOf0Processing'
      required:
        - url
      title: V1ExtractBatchBodyFilesItems0
    V1ExtractBatchBodyFilesItems1:
      type: object
      properties:
        id:
          type: string
      required:
        - id
      title: V1ExtractBatchBodyFilesItems1
    V1ExtractBatchBodyFilesItems:
      oneOf:
        - $ref: '#/components/schemas/V1ExtractBatchBodyFilesItems0'
        - $ref: '#/components/schemas/V1ExtractBatchBodyFilesItems1'
      description: >-
        An input file, given one of two ways.


        - `{ "url": "…", "name"?: "…", "processing"?: "…" }` — fetched over
        http(s) for this run and purged with it.

        - `{ "id": "…" }` — a file you already registered with `POST /v1/files`,
        reusable across runs and never re-parsed.
      title: V1ExtractBatchBodyFilesItems
    V1ExtractBatchBodyWebhook0:
      type: object
      properties:
        url:
          type: string
          format: uri
      required:
        - url
      title: V1ExtractBatchBodyWebhook0
    V1ExtractBatchBodyWebhook1:
      type: object
      properties:
        id:
          type: string
      required:
        - id
      title: V1ExtractBatchBodyWebhook1
    V1ExtractBatchBodyWebhook:
      oneOf:
        - $ref: '#/components/schemas/V1ExtractBatchBodyWebhook0'
        - $ref: '#/components/schemas/V1ExtractBatchBodyWebhook1'
      description: >-
        Where to deliver this run's events, given one of two ways.


        - `{ "url": "…" }` — a one-off https endpoint for this run only.

        - `{ "id": "whe_…" }` — a saved endpoint from `POST /v1/webhooks`. Runs
        hold the reference, so pausing or re-pointing that endpoint applies to
        this run too.


        Deliveries are at-least-once and signed — dedupe on `eventId` and verify
        against `GET /v1/webhooks/jwks.json`.
      title: V1ExtractBatchBodyWebhook
    V1ExtractBatchBody:
      type: object
      properties:
        action:
          type: string
          description: >-
            The saved action every run in the batch uses, by id or slug.
            Required.


            Inline `schema` and `hints` are deliberately not accepted here: a
            batch runs one reviewed, versionable shape over many files.
        files:
          type: array
          items:
            $ref: '#/components/schemas/V1ExtractBatchBodyFilesItems'
          description: The input files, up to 100. Each one becomes its own run.
        metadata:
          type: object
          additionalProperties:
            description: Any type
          description: >-
            Arbitrary JSON you attach to the run and get back on every read of
            it.


            Use it to carry your own identifiers — an order number, a customer
            id — so a webhook or a polled run reconciles without a lookup table.
            Capped at 10 KB serialized.
        webhook:
          $ref: '#/components/schemas/V1ExtractBatchBodyWebhook'
          description: >-
            Where to deliver this run's events, given one of two ways.


            - `{ "url": "…" }` — a one-off https endpoint for this run only.

            - `{ "id": "whe_…" }` — a saved endpoint from `POST /v1/webhooks`.
            Runs hold the reference, so pausing or re-pointing that endpoint
            applies to this run too.


            Deliveries are at-least-once and signed — dedupe on `eventId` and
            verify against `GET /v1/webhooks/jwks.json`.
        ttl:
          type: integer
          description: >-
            How long, in seconds, to keep this run and its files before purging
            them automatically.


            Defaults to 24 hours; the maximum is 604800 (7 days). The deadline
            comes back as `expiresAt` on every read of the run. Call `POST
            /v1/runs/{id}/keep` before then to clear the TTL and move the
            results into a space permanently.


            E-signature runs are exempt — an envelope waits for its signers
            however long that takes.
      required:
        - action
        - files
      title: V1ExtractBatchBody
    V1ExtractBatchItemFileOneOf0Processing:
      type: string
      enum:
        - auto
        - ocr
        - simple
        - transcribe
        - transcribe_diarize
      title: V1ExtractBatchItemFileOneOf0Processing
    V1ExtractBatchItemFile0:
      type: object
      properties:
        url:
          type: string
          format: uri
        name:
          type: string
        processing:
          $ref: '#/components/schemas/V1ExtractBatchItemFileOneOf0Processing'
      required:
        - url
      title: V1ExtractBatchItemFile0
    V1ExtractBatchItemFile1:
      type: object
      properties:
        id:
          type: string
      required:
        - id
      title: V1ExtractBatchItemFile1
    V1ExtractBatchItemFile:
      oneOf:
        - $ref: '#/components/schemas/V1ExtractBatchItemFile0'
        - $ref: '#/components/schemas/V1ExtractBatchItemFile1'
      description: >-
        An input file, given one of two ways.


        - `{ "url": "…", "name"?: "…", "processing"?: "…" }` — fetched over
        http(s) for this run and purged with it.

        - `{ "id": "…" }` — a file you already registered with `POST /v1/files`,
        reusable across runs and never re-parsed.
      title: V1ExtractBatchItemFile
    V1ExtractBatchItemError:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
      required:
        - code
        - message
      title: V1ExtractBatchItemError
    V1ExtractBatchItem:
      type: object
      properties:
        id:
          type: string
        statusUrl:
          type: string
        file:
          $ref: '#/components/schemas/V1ExtractBatchItemFile'
          description: >-
            An input file, given one of two ways.


            - `{ "url": "…", "name"?: "…", "processing"?: "…" }` — fetched over
            http(s) for this run and purged with it.

            - `{ "id": "…" }` — a file you already registered with `POST
            /v1/files`, reusable across runs and never re-parsed.
        error:
          $ref: '#/components/schemas/V1ExtractBatchItemError'
      required:
        - file
      title: V1ExtractBatchItem
    V1ExtractBatchAccepted:
      type: object
      properties:
        object:
          type: string
          enum:
            - extract_batch
        count:
          type: number
          format: double
        runs:
          type: array
          items:
            $ref: '#/components/schemas/V1ExtractBatchItem'
      required:
        - object
        - count
        - runs
      title: V1ExtractBatchAccepted
    V1ExtractBatchPostResponsesContentApplicationJsonSchemaCode:
      type: string
      enum:
        - rate_limited
      title: V1ExtractBatchPostResponsesContentApplicationJsonSchemaCode
    ExtractBatchRequestTooManyRequestsError:
      type: object
      properties:
        code:
          $ref: >-
            #/components/schemas/V1ExtractBatchPostResponsesContentApplicationJsonSchemaCode
        message:
          type: string
        retryable:
          type: boolean
        requestId:
          type: string
        docUrl:
          type: string
      required:
        - code
        - message
        - retryable
        - requestId
      title: ExtractBatchRequestTooManyRequestsError
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

```

## Examples



**Request**

```json
{
  "action": "act_01JQ8ZKMRT4V6WXYZ0ABCDEFGH",
  "files": [
    {
      "url": "string"
    }
  ]
}
```

**Response**

```json
{
  "object": "string",
  "count": 1.1,
  "runs": [
    {
      "file": {
        "url": "string",
        "name": "string",
        "processing": "auto"
      },
      "id": "string",
      "statusUrl": "string",
      "error": {
        "code": "string",
        "message": "string"
      }
    }
  ]
}
```

**SDK Code**

```python
import requests

url = "https://api.cloudraker.com/v1/extract/batch"

payload = {
    "action": "act_01JQ8ZKMRT4V6WXYZ0ABCDEFGH",
    "files": [{ "url": "string" }]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.cloudraker.com/v1/extract/batch';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"action":"act_01JQ8ZKMRT4V6WXYZ0ABCDEFGH","files":[{"url":"string"}]}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cloudraker.com/v1/extract/batch"

	payload := strings.NewReader("{\n  \"action\": \"act_01JQ8ZKMRT4V6WXYZ0ABCDEFGH\",\n  \"files\": [\n    {\n      \"url\": \"string\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.cloudraker.com/v1/extract/batch")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"action\": \"act_01JQ8ZKMRT4V6WXYZ0ABCDEFGH\",\n  \"files\": [\n    {\n      \"url\": \"string\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.cloudraker.com/v1/extract/batch")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"action\": \"act_01JQ8ZKMRT4V6WXYZ0ABCDEFGH\",\n  \"files\": [\n    {\n      \"url\": \"string\"\n    }\n  ]\n}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.cloudraker.com/v1/extract/batch', [
  'body' => '{
  "action": "act_01JQ8ZKMRT4V6WXYZ0ABCDEFGH",
  "files": [
    {
      "url": "string"
    }
  ]
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.cloudraker.com/v1/extract/batch");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"action\": \"act_01JQ8ZKMRT4V6WXYZ0ABCDEFGH\",\n  \"files\": [\n    {\n      \"url\": \"string\"\n    }\n  ]\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [
  "action": "act_01JQ8ZKMRT4V6WXYZ0ABCDEFGH",
  "files": [["url": "string"]]
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.cloudraker.com/v1/extract/batch")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```