# Conformance API > Runs that test your integration against the sandbox. ## List this application's conformance runs `GET /conformance/runs` on `https://api.finchnode.com/api/v1` Newest first. Page with nextCursor. Requires a sandbox key. Parameters: - `limit` (query, integer) - `cursor` (query, string): Opaque cursor. Pass nextCursor back to the endpoint that returned it, for the same subject and category; meta.changeCursor starts the change feed. Don't construct or edit it. Responses: - `200`: One page of runs, without their run keys. - `400`: Request validation failed. - `401`: API key is missing, invalid, or revoked. - `403`: App scope, environment, or consent does not authorize the request. - `429`: Request budget exceeded. - `503`: conformance_unavailable: conformance runs are not available on this deployment yet. Retry later; nothing was changed. ## Start a conformance run `POST /conformance/runs` on `https://api.finchnode.com/api/v1` Requires a sandbox key (ck_test_...); a live key (ck_live_...) receives 403 sandbox_only, and a suspended application 403 app_suspended. An application whose status is not sandbox receives 409 app_not_sandbox: an application has one webhook URL and signing secret across environments, and a run sends deliberately corrupted webhook probes, so run conformance on a separate sandbox application. One run can be open per application (409 run_in_progress). A run cancelled or expired before its creation finished answers 409 run_not_open, and its key is revoked without being shown. The response carries run_key, a sandbox key whose requests are attributed to the run, shown only in this response and revoked when the run ends. Configure the application with it and create a Connect session; FinchNode completes the session as the patient with the run's scenario, then forces up to two rate limits (retry each forced 429 no sooner than Retry-After), revokes consent, and sends webhook probes. A run that never gets a session expires 60 minutes after creation. A body field other than scenario and sync_mode, an unknown sync_mode, or a continuous run on an application whose sync mode is one-time returns 400 invalid_request; a scenario that is not a record scenario returns 400 invalid_scenario. Body: - `scenario` (string, required): A record scenario; its synthetic patient is the run's subject. - `sync_mode` (string): continuous adds the incremental-change check and needs an application whose sync mode is continuous. Responses: - `201`: Run created. run_key is shown only here. - `400`: Request validation failed. - `401`: API key is missing, invalid, or revoked. - `403`: App scope, environment, or consent does not authorize the request. - `409`: Request conflicts with resource state or idempotency history. - `413`: Request body exceeds 64 KiB. - `429`: Request budget exceeded. - `503`: conformance_unavailable: conformance runs are not available on this deployment yet. Retry later; nothing was changed. ## Retrieve a conformance run `GET /conformance/runs/{runId}` on `https://api.finchnode.com/api/v1` The live phase, each check with its evidence (counts, timings, and status codes), and, once the run ends, its verdict. Run and session polls are never forced and never graded. Requires a sandbox key. Parameters: - `runId` (path, string, required) Responses: - `200`: The run, without its run key. - `401`: API key is missing, invalid, or revoked. - `403`: App scope, environment, or consent does not authorize the request. - `404`: App-scoped resource does not exist. - `429`: Request budget exceeded. - `503`: conformance_unavailable: conformance runs are not available on this deployment yet. Retry later; nothing was changed. ## Stop waiting in the current phase `POST /conformance/runs/{runId}/advance` on `https://api.finchnode.com/api/v1` Takes no body. The current phase is graded now with what was observed and the run moves to the next phase, so advancing early can leave its checks inconclusive. The session phase ends only when the run's Connect session completes, and a probes phase cannot be advanced while its probes are being sent (409 phase_not_advanceable); a run that has ended returns 409 run_not_open. Requires a sandbox key. Parameters: - `runId` (path, string, required) Responses: - `200`: The run after the phase ended. - `400`: Request validation failed. - `401`: API key is missing, invalid, or revoked. - `403`: App scope, environment, or consent does not authorize the request. - `404`: App-scoped resource does not exist. - `409`: Request conflicts with resource state or idempotency history. - `429`: Request budget exceeded. - `503`: conformance_unavailable: conformance runs are not available on this deployment yet. Retry later; nothing was changed. ## Cancel a conformance run `POST /conformance/runs/{runId}/cancel` on `https://api.finchnode.com/api/v1` Takes no body. Ends an open run as cancelled and revokes its run key; a run that has ended returns 409 run_not_open. Requires a sandbox key. Parameters: - `runId` (path, string, required) Responses: - `200`: The cancelled run. - `400`: Request validation failed. - `401`: API key is missing, invalid, or revoked. - `403`: App scope, environment, or consent does not authorize the request. - `404`: App-scoped resource does not exist. - `409`: Request conflicts with resource state or idempotency history. - `429`: Request budget exceeded. - `503`: conformance_unavailable: conformance runs are not available on this deployment yet. Retry later; nothing was changed. ## Read a conformance report `GET /conformance/reports/{token}` on `https://api.finchnode.com` (no key) Public JSON behind the report's token (links.report on the run): no key, Cache-Control no-store, readable from any origin without credentials, and limited per network address. The report names the application only by its name and carries no subject, session, key, or record. Reports are kept for 90 days. Parameters: - `token` (path, string, required) Responses: - `200`: The report. - `404`: not_found. No report has that token. - `429`: rate_limited. Too many requests from this network; honor Retry-After. - `503`: conformance_unavailable: conformance runs are not available on this deployment yet.