# Signal

> Signal diagnoses production voice agents. It tells you what to fix and whether the fix worked.

- [Introduction](https://docs.signalmd.dev/index.md): Signal tells the owner of a production voice agent what to fix and whether the fix worked.
- [Quickstart](https://docs.signalmd.dev/quickstart.md): Sign up, connect a Retell agent, approve its brief, import calls and read your first issues.
- [How Signal works](https://docs.signalmd.dev/concepts/how-signal-works.md): What you get from Signal, from the first calls on your board to knowing whether a fix worked, and what you can rely on in what it says.
- [The brief](https://docs.signalmd.dev/concepts/the-brief.md): The short document that says what your agent is for and what a good call is. Signal drafts it, you correct it, and every number is measured against it.
- [Calls and flow](https://docs.signalmd.dev/concepts/traces.md): What you see on a call page and on the Flow page, and why Signal keeps each call's full record.
- [Lanes](https://docs.signalmd.dev/concepts/lanes.md): The five places a defect can live: Hearing, Understanding, Flow and state, Speaking and Integrations, and who usually owns each fix.
- [Issues](https://docs.signalmd.dev/concepts/issues.md): What an issue is, which issues reach the Fix and Improve sections, what each issue contains, and how Signal tells you whether your fix worked.
- [Signals](https://docs.signalmd.dev/concepts/signals.md): Small observations about moments in a call, shown on the call page. They help explain an issue and are never an issue on their own.
- [Versions](https://docs.signalmd.dev/concepts/versions.md): How Signal picks up a new version of your agent, what it compares, and how to read the verdicts it gives.
- [Connect Retell](https://docs.signalmd.dev/guides/connect-retell.md): Connect a Retell agent with an API key, keep its calls flowing in, add more agents, and replace or remove a connection.
- [Fix an issue](https://docs.signalmd.dev/guides/fix-an-issue.md): Go from an issue on the board to a shipped change in your agent, and confirm the change worked.
- [Compare versions](https://docs.signalmd.dev/guides/compare-versions.md): Check whether a change helped: where the comparison lives, how to read each verdict, what to do next, and how to get it over the API.
- [Test a fix](https://docs.signalmd.dev/guides/test-a-fix.md): Turn production calls into tests, run them against a version of your agent, and read what a pass and a fail mean.
- [AI copilot overview](https://docs.signalmd.dev/copilot/overview.md): An AI assistant that reads your issues and calls, drafts fixes to your prompt or flow, and tests them. Publishing to Retell always takes an admin's click.
- [Build](https://docs.signalmd.dev/copilot/build.md): Draft a fix, test it against your calls, compare the results and publish it to Retell from one page, with a way back.
- [Pricing](https://docs.signalmd.dev/billing/pricing.md): Signal's plans, what counts as an analysed call, and what happens when you reach an allowance.
- [Billing FAQ](https://docs.signalmd.dev/billing/faq.md): Answers about usage, upgrading, downgrading, cancelling, invoices and payments.
- [Limits and quotas](https://docs.signalmd.dev/limits.md): Plan allowances, API rate limits, the plan limit error, import size, copilot limits and when a version comparison can give a verdict.
- [Data and security](https://docs.signalmd.dev/data-and-security.md): What Signal stores from your Retell calls, who processes it, how it is secured, and how it is retained and deleted.
- [Glossary](https://docs.signalmd.dev/glossary.md): Short definitions of the terms you meet in the Signal app and docs, each linking to the page that explains it.
- [API introduction](https://docs.signalmd.dev/api/introduction.md): Use the Signal API to read issues, calls and versions from your own tools, and to wire Signal into CI.
- [Authentication](https://docs.signalmd.dev/api/authentication.md): Make an API key in the app, send it as a bearer token, and choose between read and write access.
- [MCP overview](https://docs.signalmd.dev/mcp/overview.md): Give Claude, Cursor or another AI assistant access to your Signal issues, calls, versions and tests, with read access by default.
- [Connect your client](https://docs.signalmd.dev/mcp/clients.md): Copy-paste setup for Claude Code, Claude Desktop, Cursor, VS Code and any other MCP client.
- [List agents](https://docs.signalmd.dev/api-reference/agents/list-agents.md): The workspace's agents, newest first, and the shared demo agent when it is on (marked `readOnly`). A key tied to one agent sees only that agent.
- [Get an agent](https://docs.signalmd.dev/api-reference/agents/get-an-agent.md): One agent with counts of its calls, open issues, versions and tests.
- [Get an attempt](https://docs.signalmd.dev/api-reference/runs/get-an-attempt.md): One simulated call: its transcript, the verdict on each criterion with who decided it, what Signal's own checks found, caller drift, and what played and scored it.
- [List runs](https://docs.signalmd.dev/api-reference/runs/list-runs.md): Test runs of this agent, newest first, each with its progress, cost and summary.
- [Start a run](https://docs.signalmd.dev/api-reference/runs/start-a-run.md): Plays tests (a set, or a list) against one agent version as simulated calls, optionally once per persona. This spends: the customer's Retell budget, and for a key, its monthly budget too. A run neither covers is refused with 402 `budget_error` before anything is spent; one they cover in part starts…
- [Get a run](https://docs.signalmd.dev/api-reference/runs/get-a-run.md): One run: status, progress, cost, a summary with calibrated cells counted apart, and the change from the previous comparable run.
- [List a run's attempts](https://docs.signalmd.dev/api-reference/runs/list-a-runs-attempts.md): The simulated calls of one run, newest first, without transcripts. GET .../attempts/{attemptId} has one in full.
- [Rescore a run](https://docs.signalmd.dev/api-reference/runs/rescore-a-run.md): Scores every stored attempt of a finished run again from its transcript with Signal's current scoring. No new calls are placed. A key may rescore only what the current scoring epoch would score differently, one rescore at a time, inside its monthly budget (402 when it does not cover it, 409 otherwis…
- [Get a run's result document](https://docs.signalmd.dev/api-reference/runs/get-a-runs-result-document.md): The run as one document (schemaVersion 1), the same the CLI writes and webhooks post: every cell with its attempts, verdicts and who decided them, and the change from the previous comparable run, or from `compareTo`.
- [Calibrate tests](https://docs.signalmd.dev/api-reference/runs/calibrate-tests.md): Plays each test three times with its own caller to decide whether it may gate a release: an issue test on the version its source call ran on (it must fail 2 of 3), any other on the version in production (it must pass 3 of 3). Until then a test is shown and never gates. Starts one calibration run per…
- [List calls](https://docs.signalmd.dev/api-reference/calls/list-calls.md): The agent's production calls, newest first. Calls with no start time come last. Filters combine.
- [Get a call](https://docs.signalmd.dev/api-reference/calls/get-a-call.md): One call with its analysis, who called and why, and the open issues it is evidence for. The transcript is in the call's trace.
- [Get a call's signals](https://docs.signalmd.dev/api-reference/calls/get-a-calls-signals.md): What was noticed on one call: the signals raised and the observations made. A signal is a symptom noticed on a call, not a diagnosed issue: the issues say where a problem is, why, and what to change.
- [Get a call's trace](https://docs.signalmd.dev/api-reference/calls/get-a-calls-trace.md): The call as Signal reads it: turns, tool calls, the path through the flow, latency by layer, and measurements. Facts the platform recorded, with none of its own judgements.
- [List version comparisons](https://docs.signalmd.dev/api-reference/comparisons/list-version-comparisons.md): Stored comparisons, newest version first: one per pair of consecutive versions Signal recorded.
- [Get a version comparison](https://docs.signalmd.dev/api-reference/comparisons/get-a-version-comparison.md): One stored comparison.
- [Get test coverage](https://docs.signalmd.dev/api-reference/tests/get-test-coverage.md): Signal's test plan and gaps: which calls it would test and why, coverage cells it could not fill, brief lines that get a probe, and tests it would retire. Reads only.
- [List personas](https://docs.signalmd.dev/api-reference/tests/list-personas.md): The callers a test can be played by, all of them in one response: each test's own (@source), personas read from the agent's calls, the standard callers, and custom personas. Real callers' sample lines are left out.
- [List test sets](https://docs.signalmd.dev/api-reference/tests/list-test-sets.md): The agent's test sets by name. The release set (`isRelease`) is what runs on every new version and from CI.
- [Get a test set](https://docs.signalmd.dev/api-reference/tests/get-a-test-set.md): One test set with its member test ids.
- [List tests](https://docs.signalmd.dev/api-reference/tests/list-tests.md): The agent's tests, newest first, each with its gate state and latest result. Archived tests are left out unless asked for.
- [Create a test](https://docs.signalmd.dev/api-reference/tests/create-a-test.md): Makes a test from a spec (custom or probe), or from a stored production call (`callId`, and `issueKey` to test that issue). Free: nothing runs. A refused spec is a 400 `invalid_spec`; POST .../tests/validate lists every problem.
- [Get a test](https://docs.signalmd.dev/api-reference/tests/get-a-test.md): One test with its spec, the shape create and edit take, and its criteria resolved against the current brief. Personal values stay masked.
- [Replace a test's spec](https://docs.signalmd.dev/api-reference/tests/replace-a-tests-spec.md): Replaces what the spec covers and makes a new revision. An edit that changes what is played or checked clears the calibration, so the test stops gating until calibrated again. An archived test is refused (422).
- [List a test's revisions](https://docs.signalmd.dev/api-reference/tests/list-a-tests-revisions.md): Every revision of a test, newest first, each as a spec. An attempt names the revision it ran (`testRevision`).
- [Get the test spec schema](https://docs.signalmd.dev/api-reference/tests/get-the-test-spec-schema.md): The TestSpec JSON Schema, and what this agent's specs can name: brief references, tools that take a fixture, personas and sets.
- [Validate a test spec](https://docs.signalmd.dev/api-reference/tests/validate-a-test-spec.md): Checks a spec as create (or, with `testId`, as an edit of that test) would, and stores and spends nothing. 200 whatever the result: `ok` says whether it would be stored. A read key may call it.
- [List issues](https://docs.signalmd.dev/api-reference/issues/list-issues.md): The agent's issues as its board shows them, Fix, Improve and Cause not established together, highest priority first, with any issue the live version fixed (`fellOnLive`: none of its calls shows it) after every one still happening: open ones, without consequences of another issue unless asked for. On…
- [Get an issue](https://docs.signalmd.dev/api-reference/issues/get-an-issue.md): One issue: where, why, what to change, how sure, how many evidence calls, how its calls split by version, the agent's grace period (`graceDays`) and whether the live version fixed it (`fix`), read with that grace period.
- [List an issue's evidence calls](https://docs.signalmd.dev/api-reference/issues/list-an-issues-evidence-calls.md): The calls linked to the issue as evidence, newest first, each with the samples the issue keeps from it.
- [List signals](https://docs.signalmd.dev/api-reference/signals/list-signals.md): For each signal code, how many of the agent's analysed calls in the window carry it, most calls first. A signal is a symptom noticed on a call, not a diagnosed issue: a common signal can have several causes or none worth fixing, and the issues say where a problem is, why, and what to change.
- [List versions](https://docs.signalmd.dev/api-reference/versions/list-versions.md): The agent's versions, newest first: every version whose configuration was captured and every version an analysed call ran on, with its calls and outcome rates.
- [Get a version](https://docs.signalmd.dev/api-reference/versions/get-a-version.md): One version with its calls, Got it done, Handed to a person and captured configuration.
- [Compare two versions](https://docs.signalmd.dev/api-reference/versions/compare-two-versions.md): What changed in the configuration between any two versions, not only neighbours, and what production did across them by the health board's metrics and verdicts (`result`), with the stored comparison when one exists for that pair.
- [Who am I](https://docs.signalmd.dev/api-reference/account/who-am-i.md): The principal this token resolves to: workspace, key scope and agent, and the rate limits that apply.

## OpenAPI Specs

- [openapi](/api-reference/openapi.json)


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