---
title: "Get the trace set-up for a monitor"
method: GET
path: "/api/v1/checks/{id}/trace-setup"
tags: ["Checks"]
---

# Get the trace set-up for a monitor

`GET /api/v1/checks/{id}/trace-setup`

## Request

- Base URL: `https://app.lastping.dev`
- URL: `https://app.lastping.dev/api/v1/checks/{id}/trace-setup`
- Auth: API key in header `X-Api-Key`

The exact steps to make a tool send OpenTelemetry traces, metrics and
logs to this monitor: what to write and where, the shell to run, a
test span to send and where it lands, and what the tool cannot do.
One block per tool (Claude Code, Codex CLI, Gemini CLI, Cursor, a
Python agent, a Node agent, any OpenTelemetry SDK, an OpenTelemetry
Collector), plus the tracing section of the protocol prompt, written
for an agent to carry out itself.

This is what the MCP `get_trace_setup` tool returns. It never contains
a key: the blocks name the tracing key by a placeholder, and
`POST /api/v1/checks/{id}/ingest-keys` mints one.

404 if the check does not exist in the authenticated project (no
existence oracle).

## Query parameters

- `tool` 'claude-code' | 'codex' | 'gemini' | 'antigravity' | 'cursor' | 'python' | 'node' | 'otel-sdk' | 'collector'

## Response `200`

The set-up for this monitor.

- TraceSetup: Response of `GET /api/v1/checks/{id}/trace-setup`: the trace set-up blocks for this monitor and the tracing section of the protocol prompt. It never contains a key: a block names the tracing key by the placeholder `<your tracing key>`, and `POST /api/v1/checks/{id}/ingest-keys` is how one is minted.
  - `tool` string, required: The `tool` asked for, or an empty string when every block was returned.
  - `blocks` TraceSetupBlock[], required: One block when `tool` was given, otherwise every block, in a fixed order.
    - `tool` 'claude-code' | 'codex' | 'gemini' | 'antigravity' | 'cursor' | 'python' | 'node' | 'otel-sdk' | 'collector', required
    - `title` string, required
    - `writes` string, required: One sentence saying what the set-up changes on the machine.
    - `command` string, required: The one-command set-up, or an empty string when there is none yet.
    - `steps` string[], required: Shell lines to run in order before `verify`, such as package installs and the changed start command. Empty when the set-up is only files.
    - `files` TraceSetupFile[], required: The files the set-up writes, so a person with nothing installed can do it by hand. A settings file's `content` is a fragment to merge into an existing file.
      - `path` string, required
      - `language` string, required
      - `content` string, required
      - `mode` string, required: The octal permission the file needs, such as `600` for a file that holds a credential, or an empty string for the default. A `600` file is created private (umask 077) before the credential goes in, never written first and chmod-ed after.
      - `merge` boolean, required: True when `content` is a fragment to merge into a file that may already exist and belongs to the person (a settings file, a TOML table, `.env`, a collector config): keep every other key, replace LastPing's own values on a re-run, never overwrite the file. False when `content` is the whole file, LastPing's own (a key file, the helper script).
    - `env_lines` string[], required: The same settings as `export` lines, the paste-by-hand path.
    - `verify` string, required: Sends one test span, says what a successful answer looks like and where the span lands.
    - `console_link` string, required: The console's run list for this monitor, where the test span lands.
    - `limits` string, required: What this tool cannot do, in plain words, ending with the content default.
    - `secret_in_url` boolean, required: True when the endpoint itself is the credential (Gemini CLI, which cannot send a header).
    - `bang_command` string, required: The one reviewed command a person runs inside the assistant's own session (Claude Code's or Codex's `!` prefix) to apply `bang_script`, or an empty string when the tool has none. It never contains a key.
    - `bang_script` TraceSetupFile, required
      - `path` string, required
      - `language` string, required
      - `content` string, required
      - `mode` string, required: The octal permission the file needs, such as `600` for a file that holds a credential, or an empty string for the default. A `600` file is created private (umask 077) before the credential goes in, never written first and chmod-ed after.
      - `merge` boolean, required: True when `content` is a fragment to merge into a file that may already exist and belongs to the person (a settings file, a TOML table, `.env`, a collector config): keep every other key, replace LastPing's own values on a re-run, never overwrite the file. False when `content` is the whole file, LastPing's own (a key file, the helper script).
    - `key_line` string, required: The one line a person runs in their own terminal (bash or zsh), never in a chat, to store the tracing key where this block's files read it. It asks for the key at a hidden prompt, so the key lands in neither a chat nor the shell's history, and prints `saved`. An empty string when the tool has none: the person then puts the key in place of the placeholder themselves, or, with `secret_in_url`, there is no key.
  - `prompt` string, required: The tracing section of the protocol prompt, written to an agent: tailored to `tool` when one was given, otherwise the form that names every block. Paste it into the agent, or let an agent connected over MCP read it from `get_trace_setup`.

## Other responses

- `400`: id is not a valid UUID, or `tool` is not one of the listed values (`UNKNOWN_TOOL`).
- `401`: Missing or invalid API key.
- `403`: The API key authenticated, but its scope does not reach this operation. The problem body carries `required_scope`: the tier the operation needs. Re-mint the key at that scope (Settings, `POST /api/v1/api-keys`, or the `create_api_key` MCP tool) rather than retrying — the refusal is deterministic and a retry will be refused identically.
- `404`: Check not found in this project.
- `429`: Too many requests. The per-principal fixed-window rate limit has been exceeded. Retry after the number of seconds indicated by the `Retry-After` response header. The problem body's `code` is `RATE_LIMITED`. It names this limiter specifically, so a client can tell it apart from the application-level throttles that also answer 429 with their own codes and their own, much longer, `Retry-After` values (`TEST_PING_RATE_LIMITED`, `TOO_MANY_ATTEMPTS`). Back off globally on `RATE_LIMITED`; back off on the one operation for the others. The principal is the API key for a key-authenticated request and the USER for a browser session, so every tab one person has open shares one budget.

---

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