---
canonical_url: "https://docs.composio.dev/toolkits/cradl_ai"
markdown_url: "https://docs.composio.dev/toolkits/cradl_ai.md"
product: "platform"
version: null
last_updated: null
---

# Cradl AI

Cradl AI is an API-first platform for building and operating AI-powered document extraction workflows.

- **Category:** documents & ocr
- **Auth:** S2S_OAUTH2
- **Composio-managed OAuth available?** No
- **Tools:** 11
- **Triggers:** 0
- **Slug:** `CRADL_AI`
- **Version:** 20261014_00

## Tools

### Download File

**Slug:** `CRADL_AI_DOWNLOAD_FILE`

Download document, OCR, annotation, prediction, or run-variable content from a Cradl AI file URL returned by another Cradl AI tool.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `file_url` | string | Yes | Exact https://files.api.cradl.ai URL returned by a Cradl AI resource. |
| `output_name` | string | No | Optional filename for the downloaded file. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Agent Run

**Slug:** `CRADL_AI_GET_AGENT_RUN`

Get the current state and outputs of one Cradl AI agent run. Poll this read-only tool until the run reaches a terminal status; it does not itself consume page quota.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `run_id` | string | Yes | Bare run identifier returned by Start Agent Run or List Agent Runs, such as cradl:run:... . |
| `agent_id` | string | Yes | Agent identifier that owns the run. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Document

**Slug:** `CRADL_AI_GET_DOCUMENT`

Get metadata, processing links, and annotations for one Cradl AI document by ID. This read does not consume page quota.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `document_id` | string | Yes | Document identifier returned by List Documents or document creation. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Prediction

**Slug:** `CRADL_AI_GET_PREDICTION`

Get one extracted prediction, including its status, fields, errors, and downloadable output references. This read does not consume page quota.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `prediction_id` | string | Yes | Prediction identifier returned by List Predictions or a run output. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Agent Runs

**Slug:** `CRADL_AI_LIST_AGENT_RUNS`

List processing runs for an agent, optionally filtered by status or creation/update time. Use this to discover recent extraction jobs and their run IDs.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `status` | string ("archived" | "exported" | "pending-export" | "pending-predictions" | "ready-for-review" | "review-completed" | "succeeded-predictions" | "error" | "running" | "completed" | "review-in-progress") | No | Return only runs in the selected provider-defined status. |
| `agent_id` | string | Yes | Agent identifier whose runs should be listed. |
| `max_results` | integer | No | Maximum runs to return in this page; Cradl does not document an upper bound. |
| `next_cursor` | string | No | Opaque continuation token returned by a previous call. Omit for the first page and pass it back without modification. |
| `updated_time_after` | string | No | Return only runs with updatedTime after this ISO 8601 timestamp. |
| `created_time_before` | string | No | Return only runs with createdTime before this ISO 8601 timestamp. |
| `updated_time_before` | string | No | Return only runs with updatedTime before this ISO 8601 timestamp. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Agents

**Slug:** `CRADL_AI_LIST_AGENTS`

List document-processing agents available to the connected Cradl AI workspace. Use an agent ID from this result to start an extraction run.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `max_results` | integer | No | Maximum agents to return in this page; Cradl does not document an upper bound. |
| `next_cursor` | string | No | Opaque continuation token returned by a previous call. Pass it back unchanged, or omit it for the first page. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Documents

**Slug:** `CRADL_AI_LIST_DOCUMENTS`

List documents in the connected Cradl AI workspace and discover document IDs and content/output file URLs.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `order` | string ("ascending" | "descending") | No | Sort documents in ascending or descending order. |
| `sort_by` | string | No | Sort documents by their creation timestamp. |
| `consent_id` | string | No | Optional consent-ID filter. |
| `dataset_id` | string | No | Optional dataset-ID filter. |
| `document_id` | string | No | Optional exact document-ID filter. |
| `max_results` | integer | No | Maximum documents to return in this page; Cradl does not document an upper bound. |
| `next_cursor` | string | No | Opaque continuation token returned by a previous call. Pass it back unchanged, or omit it for the first page. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Predictions

**Slug:** `CRADL_AI_LIST_PREDICTIONS`

List extracted predictions, optionally filtered by model, and discover prediction IDs and output file URLs.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `order` | string ("ascending" | "descending") | No | Sort predictions in ascending or descending order. |
| `sort_by` | string | No | Sort predictions by their creation timestamp. |
| `model_id` | string | No | Optional model identifier to filter predictions. |
| `max_results` | integer | No | Maximum predictions to return in this page; Cradl does not document an upper bound. |
| `next_cursor` | string | No | Opaque continuation token returned by a previous call. Omit it for the first page and pass it back unchanged to continue. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Process Document

**Slug:** `CRADL_AI_PROCESS_DOCUMENT`

Create a persistent Cradl agent run and document, then upload one document for asynchronous extraction in a single call. This consumes processed-page quota. It returns immediately after upload and does not poll extraction; use the composite agent_run_id only for document attachment. Poll the run with the original agent_id and returned bare run_id. Do not retry an ambiguous upload outcome automatically.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `file` | object | Yes | One PDF, image, or email file to process. |
| `name` | string | No | Optional persistent document name. |
| `agent_id` | string | Yes | Exact Cradl agent ID that should process the document. |
| `metadata` | object | No | Optional caller metadata to persist on the document. |
| `variables` | object | No | Optional variables made available to the new agent run. |
| `description` | string | No | Optional persistent document description. |
| `content_type` | string ("application/pdf" | "image/jpeg" | "image/png" | "image/tiff" | "image/webp" | "message/rfc822") | Yes | MIME type to record for the uploaded document. |
| `retention_in_days` | integer | No | Optional document retention period from 1 through 1825 days. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Start Agent Run

**Slug:** `CRADL_AI_START_AGENT_RUN`

Create a processing run for an existing Cradl AI agent. This creates persistent run state; attaching and processing document content against the run consumes the workspace's monthly processed-page quota.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `agent_id` | string | Yes | Agent identifier from List Agents. |
| `variables` | object | No | Optional variables made available to the agent run. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Upload Document to Run

**Slug:** `CRADL_AI_UPLOAD_DOCUMENT_TO_RUN`

Create a document attached to a Cradl AI agent run and upload its PDF, image, or email bytes. The upload starts asynchronous processing and consumes the workspace's monthly processed-page quota.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `file` | object | Yes | PDF, image, or email file to upload. |
| `name` | string | No | Optional human-readable document name. |
| `metadata` | object | No | Optional caller metadata to store on the document. |
| `description` | string | No | Optional document description. |
| `agent_run_id` | string | Yes | Composite agent run ID from Start Agent Run's id field, containing the agent and run IDs and optionally an organization prefix. |
| `content_type` | string ("application/pdf" | "image/jpeg" | "image/png" | "image/tiff" | "image/webp" | "message/rfc822") | Yes | MIME type of the document file. |
| `retention_in_days` | integer | No | Optional retention period in days, from 1 through 1825. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |