Tarseek API · Pre-production

Request traces

Inspect a request with GET /v1/requests/{request_id} and a Bearer API key granted requests:read. This permission reads metadata for the entire project, including requests made by other project keys. Existing keys do not receive it automatically. Inactive or expired keys cannot inspect requests.

Lookup returns measured timing, aggregate attempt tokens, catalog-estimated cost and provider attempt metadata. Unknown measurements remain null. Requests outside the project return the same 404 as missing requests. Prompts, responses, credentials, customer labels and client request IDs are excluded. Authentication failures before project identification have no project request record to retrieve.

Signed trace delivery

Project owners/admins configure one destination on the API keys page. Supply a public HTTPS URL on port 443, enable delivery and save the signing secret shown once. Query parameters, credentials, private addresses and redirects are not supported. DNS is checked for every attempt, and the verified address is pinned while TLS verifies the original hostname.

Finished requests are delivered after the response is complete. Inference does not wait for that delivery. Each event has an id, type, schema version, and data. The type is request.completed, including failed or cancelled requests, or destination.test. Delivery covers requests started after you enable the destination and created within seven days.

Verify a signature

Read X-Tarseek-Timestamp, X-Tarseek-Signature and X-Tarseek-Event-Id. Reject timestamps outside a five-minute tolerance. Verify the signature using the exact raw request body before parsing JSON, then durably deduplicate by event ID. Acknowledge with a 2xx response after accepting the event.

import hashlib, hmac, time

def verify(raw_body, timestamp, signature, secret):
    if abs(time.time() - int(timestamp)) > 300:
        return False
    expected = "v1=" + hmac.new(
        secret.encode(), timestamp.encode() + b"." + raw_body,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

Retries, rotation and retention

Delivery is at least once: a crash after receipt but before recording success can cause a duplicate with the same event ID and payload. Network failures, 408, 425, 429 and 5xx responses retry up to eight times with exponential backoff and jitter. Other non-2xx responses fail immediately. A manager can retry a retained failure from the history panel. Test events are limited to one per minute.

Every configuration save creates a new version and cancels queued events from the previous version, including on signing-secret rotation. Configure the receiver for the new secret before sending a test. Successful/cancelled payloads are cleared; failed payloads expire after seven days and delivery history after 30 days. Account deletion disables delivery and removes destinations and their queue records.

These are metadata-only Tarseek webhooks, not an OpenTelemetry collector or prompt/response logging service. All eligible requests are exported; configurable sampling is not included. Alert notifications are separate from request traces.

GET, PUT /v1/projects/{id}/trace-destination
POST /v1/projects/{id}/trace-destination/test
GET /v1/projects/{id}/trace-deliveries?offset=0
POST /v1/projects/{id}/trace-deliveries/{event_id}/retry

Management endpoints require a dashboard session and owner/admin membership. PUT requires expected_version (0 on creation), url and active, with optional rotate_secret. A stale version returns 409; reload the saved configuration before retrying your edit.