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

# VLM Run

VLM Run provides multimodal agents, structured extraction, predictions, files, skills, feedback, and evaluation APIs.

- **Category:** ai document extraction
- **Auth:** API_KEY
- **Composio-managed OAuth available?** N/A
- **Tools:** 11
- **Triggers:** 0
- **Slug:** `VLM_RUN`
- **Version:** 00000000_00

## Tools

### Create Skill

**Slug:** `VLM_RUN_CREATE_SKILL`

Create a reusable skill from exactly one uploaded zip, prompt, or chat session.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | No | Skill name; required with file_id and optional for prompt or session sources. |
| `prompt` | string | No | Prompt that becomes SKILL.md; provide exactly one skill source. |
| `file_id` | string | No | Uploaded skill zip ID; provide exactly one of file_id, prompt, or session_id. |
| `is_public` | boolean | No | Whether the new skill is publicly accessible. |
| `session_id` | string | No | Chat session whose history becomes the skill source; provide exactly one skill source. |
| `description` | string | No | Skill description; required with file_id and optional for prompt or session sources. |
| `json_schema` | object | No | Optional output JSON schema; allowed only with a prompt source. |

#### 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 |

### Discover Extraction Schemas

**Slug:** `VLM_RUN_DISCOVER_EXTRACTION_SCHEMAS`

List supported structured-extraction domains, or return the full JSON schema for one domain when domain is provided.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `config` | object | No | Typed generation options to apply when resolving a domain schema. Used only when domain is provided. |
| `domain` | string | No | Domain identifier to resolve, such as document.invoice. Omit it to list all supported extraction domains. |

#### 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 |

### Execute Agent

**Slug:** `VLM_RUN_EXECUTE_AGENT`

Start a VLM Run agent execution from an existing agent name or inline configuration over multimodal inputs. Execution may consume credits and is asynchronous by default; poll the returned ID with VLM_RUN_GET_RUN.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `batch` | boolean | No | Run asynchronously when true. |
| `model` | string | No | Orion model override; omit to use the skill or agent default. |
| `config` | object | No | Inline execution behavior used to identify or configure the agent. |
| `inputs` | object | No | Named typed media content or plain JSON values matching the agent input schema. |
| `metadata` | object | No | Caller metadata and data-governance settings. |
| `agent_name` | string | No | Name and optional version of an existing agent, such as agent-name:latest. |
| `request_id` | string | No | Caller-selected unique request identifier. |
| `callback_url` | string | No | HTTPS URL called when asynchronous execution completes. |

#### 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 |

### Extract Structured JSON

**Slug:** `VLM_RUN_EXTRACT_STRUCTURED_JSON`

Start structured JSON extraction from images, a document, a video, or audio using a domain, custom schema, or skill. Extraction may consume credits; document, video, and audio runs are asynchronous by default, so poll the returned prediction ID with VLM_RUN_GET_RUN.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `url` | string | No | Public media URL; for document, video, or audio use exactly one of url or file_id. |
| `batch` | boolean | No | Override asynchronous processing; omit to preserve the modality-specific provider default. |
| `model` | string | No | Structured-extraction model or quality variant, such as vlm-1:fast. |
| `config` | object | No | Generation, schema, skill, quality, and media options. |
| `domain` | string | No | Extraction domain; required for audio and optional for other modalities when config supplies a skill or custom schema. |
| `images` | array | No | Image URLs or base64-encoded images; required only for image modality. |
| `file_id` | string | No | Uploaded file ID; for document, video, or audio use exactly one of file_id or url. |
| `metadata` | object | No | Metadata and data-handling preferences for the prediction. |
| `modality` | string ("image" | "document" | "video" | "audio") | Yes | Media type to process; selects the matching generation endpoint. |
| `request_id` | string | No | Caller-selected request identifier, sent upstream as id. |
| `callback_url` | string | No | Callback URL for asynchronous completion delivery. |

#### 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 |

### Find Files

**Slug:** `VLM_RUN_FIND_FILES`

List uploaded files or find one by file ID or MD5 hash. In list mode, use offset and limit until has_more is false.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | Maximum files in list mode (1-1000). |
| `offset` | integer | No | Zero-based list offset; sent upstream as skip and used only when no selector is supplied. |
| `file_id` | string | No | Exact uploaded file ID; mutually exclusive with md5_hash. |
| `md5_hash` | string | No | Exact 32-character MD5 hex digest used for deduplication lookup; mutually exclusive with file_id. |
| `generate_public_url` | boolean | No | Whether ID lookup should generate a temporary public URL. |

#### 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 |

### Find Skills

**Slug:** `VLM_RUN_FIND_SKILLS`

List VLM Run skills or find one exact skill by ID, name, and optional version. In list mode, continue from next_offset while has_more is true.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | No | Exact skill name; mutually exclusive with skill_id. |
| `limit` | integer | No | Maximum skills to return in list mode (1-1000). |
| `offset` | integer | No | Zero-based list offset; used only when no selector is supplied. |
| `grouped` | boolean | No | Request grouped skill results in list mode. |
| `version` | string | No | Optional exact skill version used only with name. |
| `order_by` | string ("created_at" | "updated_at" | "name") | No | Sort field in list mode. |
| `skill_id` | string | No | Exact skill ID; mutually exclusive with name. |
| `descending` | boolean | No | Sort descending in list mode. |

#### 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 Run

**Slug:** `VLM_RUN_GET_RUN`

Get the current status and result of one structured-extraction prediction or agent execution; call repeatedly to poll asynchronous work.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `run_id` | string | Yes | Prediction or agent execution ID returned by a run or list tool. |
| `run_type` | string ("prediction" | "agent_execution") | Yes | Kind of run to retrieve. |

#### 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:** `VLM_RUN_LIST_AGENTS`

Return agents available to the connected account for selection before execution.

#### 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 Artifacts

**Slug:** `VLM_RUN_LIST_ARTIFACTS`

List artifact metadata belonging to exactly one chat session or agent execution. Use offset and limit to traverse pages until has_more is false.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | Maximum artifacts to return (1-1000). |
| `offset` | integer | No | Zero-based artifact offset sent upstream as offset. |
| `session_id` | string | No | Parent chat session ID; provide exactly one of session_id or execution_id. |
| `execution_id` | string | No | Parent agent execution ID; provide exactly one of execution_id or session_id. |

#### 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 Runs

**Slug:** `VLM_RUN_LIST_RUNS`

List structured-extraction predictions or agent executions for the connected account. Use offset and limit to traverse pages until has_more is false.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | Maximum runs to return (1-1000). |
| `offset` | integer | No | Zero-based number of runs to skip; sent upstream as skip. |
| `run_type` | string ("prediction" | "agent_execution") | Yes | Kind of run to list. |

#### 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 File

**Slug:** `VLM_RUN_UPLOAD_FILE`

Upload a local file to VLM Run for extraction, agent input, or skill creation. Retain the returned file ID for tools that consume uploaded files.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `file` | object | Yes | Local file to upload through Composio's file store. |
| `purpose` | string ("assistants" | "batch" | "fine-tune" | "vision" | "datasets") | No | Provider purpose assigned to the uploaded file. |
| `generate_public_url` | boolean | No | Whether to include a temporary public URL in the response. |

#### 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 |