Test and fix a flow
Tests a graph with simulated calls, reviews what happened, fixes what the review found and tests the fix. Nothing is saved. It answers 202 straight away with a job that usually finishes in 2–6 minutes: poll Get a flow test.
What to test with: simulate invented callers written from your brief (2 by default), examples (your real calls, each caller replayed against the graph), calls (transcripts of test calls you made), or a mix. rounds is the most revisions to make (1–3), and verify tests each revision again. variables are test values for the call variables. agent_id links the job to an agent so you can find it later.
Simulated calls are text only: no phone rings and no tool runs. This charges your wallet once, when the job ends, for every model call it made. 10 per workspace per hour.
Authorizations
Your workspace secret key, sk_live_ followed by 32 hex characters. Create one in the console under Developers.
Body
The graph to test and what to test it with: calls (test calls you made), simulate (simulated calls), or both. At least one test: with neither, 400 invalid_request.
The graph to test, as GET /v2/agents/{id}/flow or POST /v2/agents/flow/generate returns it. Validated like PUT /flow (400 invalid_flow).
Optional: the agent this test is for, one of this workspace's agents (404 not_found otherwise). The job records it, and GET /v2/agents/{id}/flow/refinement answers the agent's latest job for 24 hours, so a client can let the test run on in the background.
1 - 64Optional: the business's requirements for the agent (the brief it was generated from). The review judges the flow against it and a revision keeps to it. Treated as data, never as instructions to the API.
20000Optional: 1-5 transcripts of test calls you made with this flow, one AGENT:/CALLER: turn per line (POST /v2/agents/flow/transcribe turns a recording into one). The review reads them as real calls (speech recognition errors are not held against the flow); a revision is verified by replaying each call's caller against it.
1 - 5 elementsOptional: transcripts of the business's real calls (2-10, together at most 200,000 characters), as given to generate. Their callers are replayed against the flow (simulate), and the review checks each replay against its original: coverage, order and what the original agent did well.
2 - 10 elementsOptional language code or name for the spoken lines (for example hi, en or Hinglish). Without it the brief decides.
32Optional: the agent's call time limit. The review flags a main path that cannot finish inside it.
30 <= x <= 1800The model that reviews the test calls and revises the graph: gemini-3.8-flash (Gemini 3.8 Flash), claude-opus-5.5 (Claude Opus 5.5) or gpt-6-sol (GPT-6 Sol). Omitted: gemini-3.8-flash. Simulated calls do not run on it: both sides run on the model your tier's live calls run on (falling back to gemini-3.8-flash when that is unavailable).
gemini-3.8-flash, claude-opus-5.5, gpt-6-sol The most revisions to make. Default 1: test, review, revise once, then re-test and review the revision to report what remains.
1 <= x <= 3Simulated calls in the first round. With examples they are REPLAYS of the examples (the original callers played again against this flow): by default every example up to 5, the most different first, and never more than there are examples. Without examples they are invented callers: 2 by default. With calls the default is 0 (the calls are the test). Every later round runs the same callers again, so before and after are comparable.
0 <= x <= 5Optional test values for the call variables the graph reads as {{name}} (each key at most 64 characters). Every simulated caller gets plausible synthetic values for the rest, consistent with the caller.
Re-test the graph after each revision with the same simulated callers (and a replay of every real call's caller, at most 5 replays a round) and review it again; revise again while rounds remain. false: one review and at most one revision, not re-tested.
Response
Started
The agent the request named, or null.
The test calls the job was given, tidied to one AGENT:/CALLER: turn per line as they were tested; tests[].source.index (kind call) points into this list. Kept with the job (24 hours), readable only by its workspace; never logged.
5What the job costs: every simulated turn on the live-call model at the text channel's LLM rates (₹14.38 / ₹57.52 per million input / output tokens), every hosted call (the callers, a fallback, the reviews and revisions) at the provider's reported cost × ₹88 × 1.2 (its per-token rates when none is reported), rounded up once to a paisa. So far while running; once finished (succeeded, failed or canceled), the amount charged to the wallet in one flow_generation transaction described "Flow test · · … tokens".
The example calls the job was given, as it used them, in order: a replay's tests[].source.index (kind example) points into this list, so a client can show each replay beside its original, and resending them with the current flow tests the same calls again. Kept with the job (24 hours), readable only by its workspace; never logged.
10What the first review found in the graph sent.
The job id (GET /v2/agents/flow/refine/{id}) and the reference of its wallet transaction (kind flow_generation). Quote it in a support request.
^frf_[0-9A-Z]{26}$The flow revision of the graph the job was given (the graph under test).
The model that reviews and revises.
gemini-3.8-flash, claude-opus-5.5, gpt-6-sol round: the test round under way (1-based); rounds: the most there can be (1, plus 1 per revision when verify is true: 2 by default); tests_done of tests_total: this round's tests.
What the last review found: with verify, in the final graph; without, in the graph sent.
The test rounds finished so far, in order.
4The model simulated calls run on: the LLM your tier's live calls run on, as that stack names it (for example voice-agent), or gemini-3.8-flash when that model was unavailable, switched off or failed during the job (the job then falls back for good; each test names its model).
What a running job is doing; done once it succeeded; where it stopped once it failed or was canceled.
writing_scenarios, simulating, reviewing, revising, verifying, done canceled: stopped with POST /v2/agents/flow/refine/{id}/cancel; what had answered is charged and the rounds that finished are kept.
running, succeeded, failed, canceled Every model call's tokens, simulated turns included, summed. So far while running.
Once succeeded: whether flow differs from the graph sent.
Why a failed job failed.
Once succeeded: the final graph — the last valid revision, or the graph sent when nothing was changed (changed false). It passes every rule PUT /v2/agents/{id}/flow applies. Not saved.
Once succeeded: the final graph's flow revision.
Once succeeded: the variables as an agent input_schema, ready to save beside the flow.
Once succeeded: the call variables the final graph reads as {{name}}. When nothing changed, every one is typed string.
32