API introduction

The Signal API gives your own tools the data the web app shows: agents, calls and their traces, signals, issues, versions, comparisons, tests and runs. With a write key it can also create and edit tests and start runs. The MCP server calls this same API. The reference in this tab is generated from the API, so it lists the operations that exist now. This page covers what every operation has in common.

Base URL

https://first-signal-api.fly.dev/v1

Every path in the reference starts with /v1. The OpenAPI document is at GET /v1/openapi.json and needs no key.

Make your first request

Make a key in the app, then ask the API who you are. The values below are examples.

Terminal

export SIGNAL_API_KEY="sig_your_key"

curl -i https://first-signal-api.fly.dev/v1/me \
  -H "Authorization: Bearer $SIGNAL_API_KEY"

Response body, read key

{
  "object": "principal",
  "kind": "key",
  "organizationId": "org_2example",
  "userId": null,
  "key": {
    "id": "3f1c2d4e-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
    "scope": "read",
    "agentId": null,
    "monthlyBudgetUsd": null
  },
  "rateLimits": {
    "all": { "perMinute": 600, "burst": 120 },
    "write": { "perMinute": 60, "burst": 20 }
  }
}

A 401 means the key is missing, wrong or revoked. See Authentication.

Resources

Every path except /v1/me and /v1/agents starts with /v1/agents/{agentId}, so find the agent id first.

Resource	What it holds	Operations
Account	The key, its scope and budget, your rate limits	Who am I
Agents	The voice agents connected to the workspace	List agents, get an agent
Calls	Imported production calls, their traces and signals	List calls, get a call, its trace, its signals
Signals	Each signal code seen across calls, with counts	List signals
Issues	Diagnosed problems, with the calls behind them	List issues, get an issue, its evidence calls
Versions	Agent versions, outcome rates, the difference between two	List versions, get a version, compare two
Comparisons	Stored measurements of one version against another	List comparisons, get one
Tests	Tests, test sets, personas and coverage	List tests, get a test, revisions, spec schema, validate a spec, test sets, personas, coverage. Write: create a test, replace a spec
Runs	Test runs, their simulated calls, and results	List runs, get a run, its result, its attempts, get an attempt. Write: start a run, rescore a run, calibrate tests

Validating a spec is a POST that stores and spends nothing, so a read key can call it. Scope follows what an operation does, not its HTTP method. Calibrate tests needs a signed-in session. Every API key is refused with 403 and the code people_only, whatever its scope. It plays each test three times and spends like a run. For the order to call things in, see Fix an issue and Test a fix.

Conventions

JSON in and out, with camelCase fields. Ids are UUIDs. Timestamps are ISO 8601 in UTC, such as 2026-10-02T14:03:07.120Z.
Every response has a Request-Id header (req_ and 24 hex characters), repeated in error bodies. Quote it when you report a problem.
A path under /v1/agents/{agentId} returns 404 for an agent that does not exist, belongs to another workspace, or is not the one your key is tied to.

Errors

Every response that is not a success has the same body.

Response body, 400

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_cursor",
    "message": "This cursor is malformed. Pass `nextCursor` from a previous page unchanged.",
    "param": "cursor",
    "requestId": "req_8c1f0e2b4a6d9e3f7a5c1b0d"
  }
}

Branch on type, which follows from the status: invalid_request_error (400, 415, 422), authentication_error (401), budget_error (402), permission_error (403), not_found_error (404), conflict_error (409), rate_limit_error (429) and api_error (500). code names the reason and is stable within /v1. message is for people, so do not parse it. param names the field at fault, or is null. New codes can appear: treat an unfamiliar code as the general case of its type.

Status	`code`	When
400	`invalid_parameter`, `invalid_cursor`, `invalid_body`, `invalid_request`	A field failed validation, the cursor is not from a previous page, the body is not JSON, or the request was refused. `param` names the field
400	`invalid_spec`, `invalid_run`, `tests_archived`	A test spec has problems (validate a spec lists them all), the run was refused (for example, a persona the agent does not have), or it names an archived test. Nothing runs
401	`missing_authorization`, `invalid_api_key`, `invalid_token`	No bearer header, an unknown or revoked key, or an expired session token
402	`quota_exceeded`	The plan’s simulated test calls for the period do not cover the run. `error.quota` gives `metric`, `limit`, `used`, `plan` and `upgradePath`. Nothing was spent
402	`budget_exceeded`	The key’s monthly budget, the agent’s test budget or the workspace’s AI model allowance does not cover the request
402	`testing_not_configured`	Testing is off for the agent, or it has no Retell test key
403	`key_read_only`, `people_only`, `demo_read_only`	A read key called a write operation, an API key called a person-only one, or a write to the shared demo agent
404	`agent_not_found`, `route_not_found`, and a `_not_found` code for each other resource, such as `call_not_found`	The agent, resource or path does not exist for this key
409	`rescore_not_allowed`	The run cannot be rescored now. A key may rescore only what current scoring would score differently, one run at a time
422	`not_runnable`, `not_calibratable`, `unprocessable`	The tests cannot be played against that version, nothing could be calibrated, or the request was well formed and refused
429	`rate_limited`, `too_many_failed_authentications`	A bucket is empty, or this address has failed authentication too often. See `Retry-After`
500, 503	`internal_error`, `auth_not_configured`	A fault on Signal’s side, or sign-in is not set up on the server

A 402 quota_exceeded is a plan limit, so do not retry it as it is. Limits and quotas shows the full response.

Pagination

Operations that return many items take limit (1 to 100, default 25) and cursor, and return a list.

Response body

{
  "object": "list",
  "data": [],
  "hasMore": true,
  "nextCursor": "eyJ2Ijoi..."
}

Pass nextCursor back as cursor for the next page, and stop when hasMore is false. Treat the cursor as opaque and send it back unchanged.

Rate limits

Each API key, or signed-in person, can send 600 requests a minute with a burst of 120. A write also draws from a tighter bucket of 60 a minute with a burst of 20. Every response carries RateLimit-Limit (the bucket size), RateLimit-Remaining and RateLimit-Reset (seconds until full) for the tighter bucket the request drew from. A refused request is a 429 with rate_limited and a Retry-After header in seconds. Wait that long, then retry. The MCP server draws from the same buckets. The workspace as a whole, the AI-backed routes and failed authentications have limits too. Limits and quotas lists them all.

Runs take time

Start a run, rescore a run and calibrate tests answer at once with 202. The simulated calls play afterwards. Poll Get a run until status is complete, refused or failed, then read the result. A run is checked whole against the plan before it starts. If the plan’s simulated test calls do not cover it, it is refused with quota_exceeded and nothing plays. A run Signal started itself can show awaiting_approval when it is over the agent’s monthly test budget. Started through the API, the same run is refused with a 402. No key can approve a run. To be told instead of polling, add a webhook endpoint under API keys in the app. When a run ends, Signal posts its result document to every endpoint, and retries a failed delivery 5 more times over about 7 hours.

Retries and idempotency

The API takes no idempotency keys. Retrying a read is safe. Retry a 429 after Retry-After, and a 500 or a dropped connection with a growing delay. A write that timed out may have taken effect, so read the resource before you send it again.

Versioning

The version is in the path. Within /v1, changes only add: operations, optional parameters, response fields, error codes, and values in a field with a fixed set of values. Ignore fields you do not recognise, and treat an unknown value as “other”. Removing or renaming a field, a new required parameter, stricter validation, and any change to the error body or pagination need /v2, which would run beside /v1.

Get started

MCP server

API reference

API introduction

Base URL

Make your first request

Resources

Conventions

Errors

Rate limits

Runs take time

Retries and idempotency

Versioning

Next steps

Authentication

Limits and quotas

​Base URL

​Make your first request

​Resources

​Conventions

​Errors

​Pagination

​Rate limits

​Runs take time

​Retries and idempotency

​Versioning

​Next steps

Authentication

Limits and quotas

Base URL

Make your first request

Resources

Conventions

Errors

Pagination

Rate limits

Runs take time

Retries and idempotency

Versioning

Next steps