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

# Create Eval Run

> Start a new eval run over a batch of calls.

### Headers

**authorization** `string` *required*

Your API key for authentication.

### Body Parameters

**call\_ids** `array of string` *required*

The call IDs to score. Between 1 and 5000 calls.

**attached\_agents** `array of objects`

The eval agents to score with. Maximum 50 agents. Each object:

**Agent attachment fields**

**eval\_agent\_id** `string` *required*

The UUID of the eval agent.

**eval\_agent\_version\_id** `string`

Pin a specific version of the agent. Omit to use the latest published version.

**weight** `number`

Relative weight of this agent in the overall score, 0-100.

**target\_level\_keys** `array of string`

Level keys considered a passing result for this agent.

**run\_mode** `string`

The scoring modality. One of `text`, `audio`, or `full`. Defaults to `text`.

**pass\_threshold\_pct** `number`

Percentage of evaluations that must pass for the run to be marked passing overall, 0-100. Omit to run without a threshold.

**workbench\_setup\_id** `string`

UUID of a workbench setup to associate with this run. Must be provided together with `workbench_setup_version_id`.

**workbench\_setup\_version\_id** `string`

UUID of the pinned workbench setup version. The version's agent roster is used when `attached_agents` is omitted. Must be provided together with `workbench_setup_id`.

**triggered\_by** `string`

How this run was initiated. One of `manual`, `auto`, or `backfill`. Defaults to `manual`.

**metadata** `object`

Key-value metadata to attach to the run. Keys and values must be strings.

> [!NOTE]
>
> You must supply either a non-empty `attached_agents` array or a `workbench_setup_version_id` (whose pinned roster supplies the agents). If you provide `workbench_setup_id` or `workbench_setup_version_id`, both fields are required together. A valid billing record must be on file before a run can start.

### Response

**id** `string`

Unique identifier for the newly created eval run.

**org\_id** `string`

The organization that owns this run.

**status** `string`

Initial status of the run. Will be `PENDING` immediately after creation.

**triggered\_by** `string`

How the run was triggered.

**run\_mode** `string`

The scoring modality for this run.

**submitted\_call\_ids** `array of string`

The call IDs submitted for scoring.

**submitted\_attached\_agents** `array of objects`

The agent attachments submitted with the run. Each object contains `eval_agent_id`, `eval_agent_version_id`, `weight`, and `target_level_keys`.

**workbench\_setup\_id** `string or null`

The associated workbench setup, if provided.

**workbench\_setup\_version\_id** `string or null`

The pinned workbench setup version, if provided.

**resolved\_call\_count** `integer`

Number of calls resolved for the run.

**resolved\_agent\_count** `integer`

Number of eval agents resolved for the run.

**resolved\_atom\_count** `integer`

Total call-by-agent evaluations to perform.

**completed\_atom\_count** `integer`

Number of evaluations completed so far.

**summary** `null`

Always `null` at creation time.

**billable\_cost\_usd** `null`

Always `null` at creation time.

**error\_code** `string or null`

Error code if the run failed, otherwise `null`.

**error\_message** `string or null`

Human-readable error message if the run failed, otherwise `null`.

**workflow\_id** `string or null`

Internal workflow identifier, if applicable.

**metadata** `object`

Key-value metadata attached to the run.

**created\_at** `string`

ISO 8601 timestamp when the run was created.

**started\_at** `null`

Always `null` at creation time.

**completed\_at** `null`

Always `null` at creation time.

```json Response theme={null}
{
  "data": {
    "id": "e5f6a7b8-c9d0-1234-efab-345678901234",
    "org_id": "f6a7b8c9-d0e1-2345-fabc-456789012345",
    "status": "PENDING",
    "triggered_by": "manual",
    "run_mode": "text",
    "submitted_call_ids": [
      "a1b2c3d4-0000-0000-0000-000000000001",
      "a1b2c3d4-0000-0000-0000-000000000002"
    ],
    "submitted_attached_agents": [
      {
        "eval_agent_id": "11111111-aaaa-bbbb-cccc-dddddddddddd",
        "eval_agent_version_id": "22222222-aaaa-bbbb-cccc-dddddddddddd",
        "weight": 100,
        "target_level_keys": ["pass"]
      }
    ],
    "workbench_setup_id": null,
    "workbench_setup_version_id": null,
    "resolved_call_count": 2,
    "resolved_agent_count": 1,
    "resolved_atom_count": 2,
    "completed_atom_count": 0,
    "summary": null,
    "billable_cost_usd": null,
    "error_code": null,
    "error_message": null,
    "workflow_id": null,
    "metadata": {},
    "created_at": "2026-05-27T10:00:00.000Z",
    "started_at": null,
    "completed_at": null
  },
  "errors": null
}
```


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