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

# Run a Published Processor

> Run an existing published document processor with the Python SDK or REST API.

> [!NOTE]
>
> This feature is currently in beta. The API may change.

Run an existing published processor with `POST /api/v1/agent`. You need a processor ID such as `cp_XXXXX` that your team can access. The processor's published contract determines the task and output format.

**Before you begin**, make sure you have:

1. A [Datalab account](https://www.datalab.to/auth/sign_up) with an [API key](https://www.datalab.to/app/keys)
2. Python 3.11+ installed
3. The Datalab SDK: `pip install datalab-python-sdk`
4. Your `DATALAB_API_KEY` environment variable set

> [!WARNING]
>
> The legacy `/api/v1/custom-processor` and `/api/v1/custom-pipeline` run endpoints and their management APIs are deprecated, with an announced sunset of October 31, 2026. Use `run_agent()` or `/api/v1/agent` for new integrations. See [migration guidance](https://documentation.datalab.to/platform/migration.md).

## Built-in Processors

The published `jats` processor produces JATS XML for scholarly articles. The
published `wcag` processor produces a tagged Accessible PDF. Both return
verification results that need review before using the artifact. See
[JATS XML and Accessible PDF](https://documentation.datalab.to/docs/recipes/document-agent/jats-and-accessible-pdf.md)
for complete examples and output fields.

## Run a Processor

```python Python SDK theme={null}
from datalab_sdk import AgentOptions, DatalabClient

client = DatalabClient()
result = client.run_agent(
    "document.pdf",
    options=AgentOptions(processor="cp_abc123"),
)
if not result.success:
    raise RuntimeError(result.error or "Processing failed")
print(result)
```

```bash cURL theme={null}
curl --fail-with-body https://www.datalab.to/api/v1/agent \
  -H "X-API-Key: $DATALAB_API_KEY" \
  -F "file=@document.pdf" \
  -F "processor=cp_abc123"

# Poll request_check_url from the submission response.
curl --fail-with-body "$REQUEST_CHECK_URL" \
  -H "X-API-Key: $DATALAB_API_KEY"
```

```python Python (requests) theme={null}
import os
import time
import requests

headers = {"X-API-Key": os.environ["DATALAB_API_KEY"]}
with requests.Session() as session:
    with open("document.pdf", "rb") as file:
        response = session.post(
            "https://www.datalab.to/api/v1/agent",
            headers=headers,
            files={"file": ("document.pdf", file, "application/pdf")},
            data={"processor": "cp_abc123"},
            timeout=60,
        )
    response.raise_for_status()
    check_url = response.json()["request_check_url"]

    delay = 0.3  # poll fast at first: most results are ready in seconds
    for _ in range(300):
        response = session.get(check_url, headers=headers, timeout=30)
        response.raise_for_status()
        result = response.json()
        if result.get("success") is False or result.get("status") == "failed":
            raise RuntimeError(result.get("error") or "Processing failed")
        if result["status"] == "complete":
            if result.get("result_url"):
                # Signed download URLs do not need the API key header.
                download = session.get(result["result_url"], timeout=60)
                download.raise_for_status()
                result = download.json()
            if result.get("success") is False:
                raise RuntimeError(result.get("error") or "Processing failed")
            print(result)
            break
        time.sleep(delay)
        delay = min(delay * 1.15, 1)
    else:
        raise TimeoutError("Processing is still running; keep the request ID")
```

The SDK polls automatically and returns an `AgentResult`. Available output fields depend on the published processor. REST clients should check `status` and `success`, then download `result_url` if the completed response provides one.

## Pin a Version

Use `processor="cp_abc123@2.0"` to pin a published version. Omitting the version runs the newest published version. Pin production integrations when you need repeatable processor behavior.

## Run Options

`AgentOptions` accepts the following options. Omitted optional values use API defaults.

| Option | Type | API default | Description |
| - | - | - | - |
| `processor` | str | Required | Published processor ID, optionally followed by `@version` |
| `mode` | str | `balanced` | `fast` caps each pass for lower cost; `balanced` uses the task's turn ceiling |
| `verification_effort` | str | `fast` | Verification effort: `fast`, `balanced`, or `accurate` |
| `return_images` | bool | `false` | Return run images inline when supported by the processor |
| `skip_cache` | bool | `false` | Run again instead of using cached output |
| `webhook_url` | str | — | Completion notification URL |
| `processing_location` | str | — | Residency region; use a `file_url` input when set |

The published processor sets its output format. Conversion options such as `output_format` are not run options on this endpoint.

## CLI

```bash CLI theme={null}
# Process one file using a published processor.
datalab agent document.pdf --processor cp_abc123 --output_dir ./output/

# Pin a version.
datalab agent document.pdf --processor cp_abc123@2.0 --output_dir ./output/
```

## Next Steps

> [card] [Python SDK](https://documentation.datalab.to/docs/welcome/sdk.md)
>
> Configure clients, handle errors, and control polling.

> [card] [API Overview](https://documentation.datalab.to/docs/welcome/api.md)
>
> Understand submission, polling, and completion responses.

> [card] [Migration Guide](https://documentation.datalab.to/platform/migration.md)
>
> Replace deprecated custom processor calls.

> [card] [Webhooks](https://documentation.datalab.to/platform/webhooks.md)
>
> Receive a notification when a run finishes.


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