---
title: "Start or repeat a synthetic agent test"
method: POST
path: "/v1/tests/run"
tags: ["agent-testing", "synthetic", "timeline"]
---

# Start or repeat a synthetic agent test

`POST /v1/tests/run`

## Request

- Base URL: `https://api.402rates.com`
- URL: `https://api.402rates.com/v1/tests/run`
- Auth: none declared

Create a free bounded synthetic run without an account. An optional finalized previous run and its token link a repeat of the same case version and scenario. No real purchase. Caller model costs remain external.

## Headers

- `X-Test-Access-Token` string: Secret short-lived run token. Omitted from reports. MCP client history may retain this argument.

## Request body

- union
  - object: Empty HTTP input returns guidance only; it performs no run operation and requires no run token.
    - `case_id` string: Versioned synthetic case identifier.
    - `case_version` string: Optional exact case version. A new run defaults to the current published version; a linked repeat retains its previous version. The resolved version is returned and stored.
    - `variant` string: Budget case: budget_first or attempts_first. Linked repeats retain the previous variant.
    - `previous_run_id` string: Optional finalized run to repeat. Its access token authenticates this start.
    - `configuration_changed` boolean: Optional caller-declared change since the previous run; not independently verified.
  - object
    - `case_id` string, required: Versioned synthetic case identifier.
    - `case_version` string: Optional exact case version. A new run defaults to the current published version; a linked repeat retains its previous version. The resolved version is returned and stored.
    - `variant` string: Budget case: budget_first or attempts_first. Linked repeats retain the previous variant.
    - `previous_run_id` string: Optional finalized run to repeat. Its access token authenticates this start.
    - `configuration_changed` boolean: Optional caller-declared change since the previous run; not independently verified.

## Response `200`

Successful response

- object

## Other responses

- `400`: Invalid test input
- `401`: Run token required or invalid
- `405`: POST required
- `409`: Run or action conflict
- `410`: Run no longer available
- `413`: Input exceeds 8192 bytes
- `415`: application/json required
- `429`: Test limit reached
- `503`: Test service unavailable

---

[API](https://skmtc.dev/402rates/apis/402rates-com.md) · [All operations](https://skmtc.dev/402rates/apis/402rates-com/llms.txt) · [OpenAPI document](https://skmtc.dev/402rates/apis/402rates-com/revisions/483a9d0a3f0b?raw)