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

# Collection Jobs

> Run metrics on demand for specific calls via the API

## Overview

Collection jobs are the programmatic way to run metrics on demand for one or many calls via the API. While [collectors](/documentation/metrics/metric-collectors) automate collection for incoming calls, collection jobs let you trigger metric processing against existing calls — whether that's backfilling a new metric across historical data or re-running after a definition change.

<Tip>
  Want to run metrics across calls from the UI? Use [Studio](/documentation/metrics/studio) in Evaluate mode ("Run a battery of metrics across a set of calls") instead. Collection jobs are designed for programmatic, at-scale use via the SDK.
</Tip>

***

## When to Use Collection Jobs

* **Backfill metrics** — Run newly created metrics on historical calls
* **Re-run metrics** — Reprocess calls after updating a metric definition
* **On-demand analysis** — Collect metrics for a specific set of calls uploaded via API
* **Scale up after testing** — You've validated a metric in Studio, now run it across many calls programmatically

***

## Creating a Collection Job

Provide an array of call IDs and the metrics you want to collect:

```typescript theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
const job = await client.metricCollectionJob.create({
  callIds: ['call-uuid-1', 'call-uuid-2', 'call-uuid-3'],
  metrics: [
    { id: 'metric-definition-uuid-1' },
    { id: 'metric-definition-uuid-2' },
  ],
})

// job.data
{
  id: 'job-uuid',
  status: 'PENDING',
  triggeredBy: 'USER_API',
  totalItems: 6,
  completedItems: 0,
  failedItems: 0,
  startedAt: null,
  completedAt: null,
  errorMessage: null,
  createdAt: '2025-01-15T10:30:00Z',
  updatedAt: '2025-01-15T10:30:00Z',
}
```

**Parameters:**

| Field     | Type      | Required | Description                                |
| :-------- | :-------- | :------- | :----------------------------------------- |
| `callIds` | string\[] | Yes      | Array of call UUIDs to process (minimum 1) |
| `metrics` | array     | Yes      | Metric definitions to collect (minimum 1)  |

<Note>
  The `totalItems` count equals `callIds.length * metrics.length` — each call-metric combination is a separate item.
</Note>

***

## Job Lifecycle

Collection jobs progress through the following statuses:

```
PENDING → PROCESSING → COMPLETED / FAILED / CANCELED
```

| Status       | Description                                   |
| :----------- | :-------------------------------------------- |
| `PENDING`    | Job created, waiting to start processing      |
| `PROCESSING` | Actively collecting metrics from calls        |
| `COMPLETED`  | All items processed successfully              |
| `FAILED`     | Job encountered errors (check `errorMessage`) |
| `CANCELED`   | Job was canceled before completion            |

### Progress Tracking

Monitor progress using these fields:

| Field            | Description                                         |
| :--------------- | :-------------------------------------------------- |
| `totalItems`     | Total number of call-metric combinations to process |
| `completedItems` | Number of items successfully processed              |
| `failedItems`    | Number of items that failed                         |
| `startedAt`      | When processing began                               |
| `completedAt`    | When processing finished                            |

***

## Monitoring Jobs

### List Collection Jobs

```typescript theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
const jobs = await client.metricCollectionJob.list()

// With filters
const completedJobs = await client.metricCollectionJob.list({
  status: 'COMPLETED',
  limit: 50,
})
```

| Parameter | Type   | Description                                                             |
| :-------- | :----- | :---------------------------------------------------------------------- |
| `limit`   | number | Max results (1-50, default: 20)                                         |
| `after`   | string | Cursor for pagination                                                   |
| `status`  | string | Filter by `PENDING`, `PROCESSING`, `COMPLETED`, `FAILED`, or `CANCELED` |

### Get a Collection Job

```typescript theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
const job = await client.metricCollectionJob.getByID('job-id')
```

Returns the full job object with current progress.

***

## Example: Studio to Production

A typical end-to-end workflow — test a metric in Studio, then run it across calls via the SDK:

<Steps>
  <Step title="Test in Studio">
    Use [Studio](/documentation/metrics/studio) to test your metric prompt against a sample call. Iterate until you're happy with the output.
  </Step>

  <Step title="Create the Metric Definition">
    Once validated, create the metric definition via the SDK:

    ```typescript theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
    const metric = await client.metric.createDefinition({
      name: 'Identity Verified',
      outputType: 'BOOLEAN',
      analysisPackageId: 'your-package-id',
      llmPrompt: 'Did the agent successfully verify the caller identity?',
      booleanTrueLabel: 'Verified',
      booleanFalseLabel: 'Not Verified',
    })
    ```
  </Step>

  <Step title="Run on Existing Calls">
    Create a collection job targeting the calls you want to analyze:

    ```typescript theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
    const job = await client.metricCollectionJob.create({
      callIds: ['call-id-1', 'call-id-2', 'call-id-3'],
      metrics: [{ id: metric.data.id }],
    })
    ```
  </Step>

  <Step title="Poll for Completion">
    ```typescript theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
    let status = 'PENDING'
    while (status !== 'COMPLETED' && status !== 'FAILED') {
      const result = await client.metricCollectionJob.getByID(job.data.id)
      status = result.data.status
      console.log(`Progress: ${result.data.completedItems}/${result.data.totalItems}`)
    }
    ```
  </Step>

  <Step title="Fetch Results">
    ```typescript theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
    const metrics = await client.call.listMetrics('call-id-1')
    console.log(metrics.data)
    ```
  </Step>
</Steps>

<Tip>
  Once you've validated the metric works well across calls, consider creating a [collector](/documentation/metrics/metric-collectors) to automatically collect it on future calls.
</Tip>

***

## What's Next

<CardGroup cols={2}>
  <Card title="Studio" icon="square-terminal" href="/documentation/metrics/studio">
    Test metrics interactively before running at scale
  </Card>

  <Card title="Collectors" icon="shield-check" href="/documentation/metrics/metric-collectors">
    Automate metric collection for incoming calls
  </Card>
</CardGroup>