---
title: "Latest example verification runs"
method: GET
path: "/v1/examples/verification"
tags: ["Content"]
---

# Latest example verification runs

`GET /v1/examples/verification`

## Request

- Base URL: `https://api.gunspec.io`
- URL: `https://api.gunspec.io/v1/examples/verification`
- Auth: one of:
  - none
  - API key in header `X-API-Key`
  - HTTP bearer

The receipts behind the "verified" badges in the documentation, for every surface. The SDK surface installs the published package into a fresh project and runs each sample exactly as printed; the API surface runs the cURL command exactly as the reference prints it, with the key substituted at run time; the MCP surface calls every tool on the hosted MCP server with its documented example arguments. This returns the most recent run for each surface and language, with the outcome of every example. Examples that would write are never run against production, since each would create a real ticket, webhook endpoint or seller offer, and are reported as `skipped` with that reason, so the counts never imply coverage the run does not have.

No API key required.

## Query parameters

- `surface` 'sdk' | 'api' | 'mcp'
- `include` 'samples'

## Response `200`

Latest example verification runs

- object
  - `success` boolean, required: Always true on a successful response. Every error carries `false` and an `error` object instead.
  - `data` object, required: The response payload.
    - `runs` SdkVerificationRun[]: The latest run per surface and language, ordered by surface then language.
      - `surface` 'sdk' | 'api' | 'mcp', required: Which promise the run is about: `sdk` for the published packages, `api` for the cURL commands the reference prints.
      - `language` 'typescript' | 'javascript' | 'python' | 'curl' | 'unity' | 'unreal' | 'godot' | 'mcp', required: The sample's own language. On an SDK run, `typescript` or `python` for the published package. On an API run, the tab of the reference it came from: `curl`, `javascript` (the TypeScript tab's generated `fetch`), `python` (its generated `requests`), or `unity`, `unreal` and `godot`, which are checked rather than executed.
      - `checkKind` 'executed' | 'static': How the run arrived at its results. `executed` ran the sample against this API. `static` could not, and checked the sample against the operation it documents instead: the Unity, Unreal and GDScript samples are fragments meant for a class, an actor or a scene, so running one would mean wrapping it in code the reference does not print.
      - `sdkVersion` string, required: What was exercised: the release installed from the registry on an SDK run, and the spec version the samples were generated from on an API run. The release rather than the version in our tree, because the badge vouches for what a reader gets today.
      - `apiHost` string, required: The API the run was executed against. Production, so the badge vouches for the live service rather than a preview.
      - `ranAt` string, required: When the run finished, ISO 8601.
      - `commitSha` string, nullable: The commit of this repository the run was started from, or null where CI did not report one.
      - `runUrl` string, nullable: The CI run, so the claim can be checked rather than taken.
      - `passed` integer, required: Examples that ran and returned what the page prints.
      - `failed` integer, required: Examples that ran and did not. A non-zero count is what takes the badge down.
      - `skipped` integer, required: Write examples, which are never run against production: each would create a real ticket, webhook endpoint or seller offer.
      - `unsupported` integer, required: Examples this SDK has no method for. The reference shows no sample for them either.
      - `examples` object[], required: Every example in the run, by the element id the SDK reference anchors on.
        - `exampleId` string, required: The element id the SDK reference anchors the sample on, which is how a result is matched back to the printed snippet.
        - `resource` string, required: SDK resource the example calls, e.g. `firearms`.
        - `method` string, required: Method on that resource, e.g. `list`.
        - `endpoint` string, required: The HTTP call the method makes, as `GET /v1/firearms`.
        - `status` 'passed' | 'failed' | 'skipped' | 'unsupported', required: Production status, one of `in_production`, `discontinued`, `out_of_production`, `in_service`, `limited_production`, `prototype`. Discontinued records are kept deliberately: a rifle built in 2004 wears parts nobody sells today.
        - `durationMs` integer: Wall-clock time the example took, in milliseconds. 0 for one that never ran.
        - `reason` string, nullable: Why it was skipped, or the tail of what it printed when it failed.
        - `hasSample` boolean, required: Whether the run stored what this example answered. Ask for it with `include=samples`.
        - `sample` unknown

## Other responses

- `400`: Validation error
- `429`: A limit was reached. `RATE_LIMITED` is the per-minute limit: wait `Retry-After` seconds (a minute) and retry. `DAILY_CAP_EXCEEDED` is the plan's daily limit, per key: nothing will be served until the counters return to zero at midnight UTC. `MONTHLY_CAP_EXCEEDED` is the plan's monthly allowance, for the whole account: nothing will be served until midnight UTC on the first of next month, or until the plan changes. For both, `Retry-After` is the seconds until then and `error.resetsAt` says when as an instant. Calls made after a refusal are refused too and do not spend the month, and a free key that keeps calling is paused, so stop at the first one and resume at the reset.
- `500`: Internal server error

---

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