---
title: "Start a Chat or Simulations test run of the agent's workflow"
method: POST
path: "/v1/agents/{agent_id}/workflow/runs"
---

# Start a Chat or Simulations test run of the agent's workflow

`POST /v1/agents/{agent_id}/workflow/runs`

## Request

- Base URL: `https://api.skysay.ai`
- URL: `https://api.skysay.ai/v1/agents/{agent_id}/workflow/runs`
- Auth: none declared

Pins the exact compiled draft or published version this run tests, so a later draft edit never retroactively changes a run already in progress. Only mode=chat is accepted here, because this is the only run this route can also advance: Simulations are started through POST /v1/agents/{agent_id}/workflow/simulations, Talk via POST /v1/agents/{agent_id}/browser-sessions with workflow_mode=talk, and Phone via POST /v1/agents/{agent_id}/workflow/phone-pin -- each mints its own run through the path that actually drives it. Chat runs are capped per organization to bound concurrent model calls on the platform test credential.

## Path parameters

- `agent_id` string, required

## Request body

- object
  - `mode` 'chat', required
  - `pinned_source` 'draft' | 'published'
  - `test_values` object: Values for the workflow's declared variables, for this Chat test only, admitted exactly as a Talk test's are: a question that compares an answer with a value compares it with these (none supplied takes its mismatch route). Refused like a call's values: 400 with reason one of call_variables_missing, call_variables_invalid, call_variables_over_budget, workflow_binding_failed, schema_pair_mismatch, per_call_text_on_workflow, agent_not_published, keypad_value_not_dialable, keypad_value_in_text, and field / where naming the variable or line (never a value).

## Response `201`

Created test run

## Other responses

- `400`: Invalid mode, no workflow, or the chat-run cap is full
- `404`: Agent has no workflow yet

---

[API](https://skmtc.dev/skysay/apis/skysay-api.md) · [All operations](https://skmtc.dev/skysay/apis/skysay-api/llms.txt) · [OpenAPI document](https://skmtc.dev/skysay/apis/skysay-api/revisions/95b8c66f99aa?raw)