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

# Runs & Schedules

> Tag your evaluations and run them on a recurring schedule.

A **run** is a batch of [simulated conversations](/concepts/simulations/overview) launched with shared configuration. A run can contain one or many conversations, for example one per test case in your [test set](/concepts/test-sets/overview), and evaluates each against your [metrics](/concepts/metrics/overview).

Runs are launched from the Simulate page (click **+** beside **Simulated** in the sidebar, or **New Simulation** on the Simulated Conversations page). This page covers organizing a run with tags, understanding the resource versions it used, and running it automatically on a schedule.

## Tagging runs

Tags label runs so you can organize and filter them — for example, by environment, release version, or test type. A run can carry up to 20 tags, each up to 200 characters.

**At launch:** Add tags in the **Tags** section of the Simulate page before you click **Launch**.

**After launch:** Use the tag control in the results header of a run, a simulation result, or an uploaded conversation's results. From there you can search existing tags, create new ones, and rename or recolour a tag.

Tags are stored on the run, so where you add one matters:

* Tagging a **run** tags every simulation in it.
* Tagging a **simulation result** tags its parent run — and therefore every simulation in that run.
* Tagging an **uploaded conversation** tags only that conversation, because each uploaded conversation has a run of its own.

**Via the API:** Pass tags in the `metadata.tags` field of the launch request, or change them later with [Update run](/api-reference/runs/update-run):

```json theme={null}
{
  "agent_id": "...",
  "persona_id": "...",
  "test_set_id": "...",
  "metadata": {
    "tags": ["regression", "v2.1", "nightly"]
  }
}
```

After launch, you can filter simulations by tag using the `tag=` filter expression (e.g., `tag="regression"`).

## Passing run metadata to an inbound SIP agent

When an inbound SIP agent needs launch-specific connection context, add the values to `metadata.customer` and reference them from the agent's custom SIP headers with `{{run_metadata.<key>}}`.

```json theme={null}
{
  "agent_id": "<agent-id>",
  "persona_id": "<persona-id>",
  "test_set_id": "<test-set-id>",
  "metadata": {
    "customer": {
      "job_id": "job-123",
      "routing_target": "wss://voice.example.com"
    }
  }
}
```

Run metadata is resolved independently for every run, so the same agent configuration can route concurrent launches using different values. See [Passing context to an inbound voice agent](/concepts/agents/connections/inbound-voice#passing-context-to-your-agent-sip) for header configuration, supported value types, and failure behavior.

## Resource versions and staleness

Coval keeps a [version history](/concepts/versioning/overview) for the resources a run uses. When you launch a run, it records the version of each resource it executed against, so its results stay interpretable even after you edit those resources later.

In the run view, Coval flags when a run executed against an **older version** than the resource's current one — a signal that the run may no longer reflect your latest configuration. When you see this, the run's results were produced by a prior version; re-run against the current configuration to compare on equal footing.

This staleness indicator is live for **agents**, **personas**, and **metrics**. Test sets are versioned too, but the run view does not yet flag a stale test-set version — that surfacing is coming.

## Scheduled runs

Any evaluation can run on a recurring cadence to catch regressions and monitor agent quality over time. A scheduled run is backed by a [template](/concepts/templates/overview) — each time the schedule fires, Coval launches a new run with that template's exact configuration (agent, personas, test set, metrics, and mutations).

### Creating a schedule

On the Simulate page, set up your run (agent, personas, test set, metrics), then choose **Launch ▾ → Schedule**. In the dialog:

* **Schedule Name** — optional; defaults to the template name.
* **Template Name** — required. The schedule is saved as a template you can reuse and edit later.
* Pick a schedule type:

<Tabs>
  <Tab title="Interval-based">
    Runs fire at a fixed cadence from when the schedule is created. Pick a preset — 15 or 30 minutes, hourly, every 6 or 12 hours, daily, weekly, or monthly — or set a custom interval anywhere from 15 minutes to 30 days.
  </Tab>

  <Tab title="Time of Day">
    Runs fire at a specific time, anchored to your local timezone.

    * **Time** — set the hour, minute, and AM/PM.
    * **Recurrence** — **Daily** (every day at that time) or **Weekly** (select which days, e.g. Mon–Fri).
  </Tab>
</Tabs>

Click **Schedule**. The schedule activates immediately.

### Managing schedules

Open **Scheduled** (from the sidebar, or the **Scheduled** button on the Simulated Conversations page). It lists every schedule with its status (**Active** or **Disabled**), name, agent, cadence, backing template, and creation date. Search by name or ID, or filter by status.

* **Enable / Disable** — pause a schedule without deleting it. Works on a single schedule or in bulk.
* **Edit Schedule** — change the name or timing. This does **not** change what gets evaluated; edit the template for that.
* **Delete** — only available once a schedule is disabled. This is permanent.

Click any schedule to open its **run history** — every run it has launched, with per-metric results, so you can spot regressions across consecutive runs.

<Note>
  To change what a schedule evaluates (agent, metrics, test cases), edit its [template](/concepts/templates/overview) — the schedule always points to it.
</Note>


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