RundialDocs

Appearance

HTTP API ​

Use the HTTP API to manage runs and send or query data.

Connect ​

The local API origin is http://127.0.0.1:8787; versioned routes start at /api/v1. Use your deployment's public API origin for remote access. Send a project API key, personal access token or session token in Authorization: Bearer <token>. See Members and API keys to create credentials.

Use the OpenAPI document for request and response schemas. The running API also serves it at /api/v1/openapi.json.

Send data ​

Start a run before sending native metrics, logs, traces or media. OTLP producers can create the run from a session; see OpenTelemetry. Call POST /api/v1/runs/start to start a run. Use the returned target identifiers in the ingest request. When authentication is enabled, send x-rundial-client (any client name, for example my-producer/1.0) and x-rundial-protocol: 1 on run-start, target-resolution and ingest requests. For retries, send x-rundial-batch-id with the same ID for every retry of a batch; use a different ID for a new batch. IDs are at most 128 characters and use letters, digits, _, ., :, or -.

The following commands use the quickstart project. Set RUNDIAL_API_KEY to its ingestion key first. projectId is the project ID, proj_default-project, not the slug.

bash
curl http://127.0.0.1:8787/api/v1/runs/start \
  -H "Authorization: Bearer $RUNDIAL_API_KEY" -H "Content-Type: application/json" \
  -H "x-rundial-client: my-producer/1.0" -H "x-rundial-protocol: 1" \
  -d '{"projectId": "proj_default-project", "kind": "training", "runName": "http-example"}'

Replace <run-id> with the runId from the first response, then send a metric point:

bash
curl http://127.0.0.1:8787/api/v1/ingest/metrics \
  -H "Authorization: Bearer $RUNDIAL_API_KEY" -H "Content-Type: application/json" \
  -H "x-rundial-client: my-producer/1.0" -H "x-rundial-protocol: 1" -H "x-rundial-batch-id: batch-0001" \
  -d '{"points": [{"projectId": "proj_default-project", "runId": "<run-id>", "metricKey": "loss", "step": 0, "timestampMs": 1767225600000, "value": 0.5}]}'

The response is {"accepted":1}.

Handle responses ​

Errors use this envelope; details may be omitted:

json
{"status":"error","error":{"code":"NOT_FOUND","message":"Run not found"},"requestId":"example"}

Treat 401 as an authentication failure and 403 as a permission failure. Follow the cursor returned by paginated endpoints to retrieve further pages. Query shapes and page sizes have server-enforced limits; see Limits.

Next steps ​