TraceStax Docs

Ingest API

The Ingest API is the HTTP interface for sending telemetry events to TraceStax. The TraceStax SDKs call this API automatically; use this reference if you are building a custom integration or sending events directly.

Base URL

https://ingest.tracestax.com

All endpoints are served over HTTPS. Plain HTTP requests are rejected.

Authentication

Every request must include a valid API key in the Authorization header using a Bearer token.

Authorization: Bearer ts_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

API keys are scoped to a project. A key beginning with ts_live_ is a production key; ts_test_ keys send events to an isolated test environment that does not affect dashboards or trigger alerts.

Retrieve or rotate your API keys from Project Settings → API Keys in the dashboard.

POST /v1/ingest

Submit a single task event. This is the primary endpoint used by SDKs when jobs execute.

Request

POST https://ingest.tracestax.com/v1/ingest
Content-Type: application/json
Authorization: Bearer ts_live_xxx

Body: a single TaskEvent object. See Event schema — TaskEvent for the full field reference.

Response

202 Accepted

{
  "ok": true
}

Example

curl

curl -X POST https://ingest.tracestax.com/v1/ingest \
  -H "Authorization: Bearer ts_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "task_event",
    "framework": "bullmq",
    "language": "typescript",
    "sdk_version": "0.4.1",
    "worker": {
      "key": "worker-1:4201",
      "hostname": "worker-1.internal",
      "pid": 4201,
      "concurrency": 5,
      "queues": ["default"]
    },
    "task": {
      "name": "SendEmailJob",
      "id": "job_01hwx3k9abc",
      "queue": "default",
      "attempt": 1
    },
    "status": "succeeded",
    "metrics": {
      "duration_ms": 543,
      "queued_ms": 88
    }
  }'

POST /v1/heartbeat

Submit a single heartbeat to confirm a worker is alive.

Request

POST https://ingest.tracestax.com/v1/heartbeat
Content-Type: application/json
Authorization: Bearer ts_live_xxx

Body: a single HeartbeatPayload object. See Event schema — HeartbeatPayload.

Response

200 OK

{
  "ok": true
}

Example

curl

curl -X POST https://ingest.tracestax.com/v1/heartbeat \
  -H "Authorization: Bearer ts_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "heartbeat",
    "framework": "sidekiq",
    "worker": {
      "key": "sidekiq-1:7823",
      "hostname": "sidekiq-1.internal",
      "pid": 7823,
      "concurrency": 10,
      "queues": ["default", "mailers"]
    },
    "timestamp": "2026-03-24T14:22:00.000Z"
  }'

POST /v1/snapshot

Submit a single queue snapshot.

Request

POST https://ingest.tracestax.com/v1/snapshot
Content-Type: application/json
Authorization: Bearer ts_live_xxx

Body: a single SnapshotPayload object. See Event schema — SnapshotPayload.

Response

202 Accepted

{
  "ok": true
}

Example

curl

curl -X POST https://ingest.tracestax.com/v1/snapshot \
  -H "Authorization: Bearer ts_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "snapshot",
    "framework": "rq",
    "worker_key": "rq-worker-2:11042",
    "queues": [
      {
        "name": "default",
        "depth": 24,
        "active": 3,
        "failed": 0,
        "throughput_per_min": 18.5
      }
    ],
    "timestamp": "2026-03-24T14:22:00.000Z"
  }'

POST /v1/lineage

Submit a lineage record linking a parent task to its child tasks. Requires a Starter plan or above.

Request

POST https://ingest.tracestax.com/v1/lineage
Content-Type: application/json
Authorization: Bearer ts_live_xxx

Body:

{
  parent_id: string;       // ID of the parent task
  children: Array<{        // 1–500 child entries
    id: string;
    task_name: string;
  }>;
  chain_id: string;        // Workflow chain identifier
}

Response

202 Accepted

{
  "ok": true
}

Example

curl

curl -X POST https://ingest.tracestax.com/v1/lineage \
  -H "Authorization: Bearer ts_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "parent_id": "job_01hwx3k9abc",
    "children": [
      { "id": "job_01hwx3k9def", "task_name": "ProcessPaymentJob" },
      { "id": "job_01hwx3k9ghi", "task_name": "SendReceiptJob" }
    ],
    "chain_id": "order-flow-12345"
  }'

GET /v1/ping

Verify that your API key is valid and return basic project information. Useful for SDK initialisation and connection checks.

Request

GET https://ingest.tracestax.com/v1/ping
Authorization: Bearer ts_live_xxx

Response

200 OK

{
  "ok": true,
  "data": {
    "project_id": "proj_01hwx3k9abcdef0123456789",
    "project_name": "orders-service",
    "workspace_id": "ws_01hwx3k9abcdef0123456789",
    "plan_tier": "pro"
  }
}

Rate limits

Limit	Value
Requests per minute	500 per workspace
Maximum request body size	256 KB

Rate limits are enforced per workspace. If your application runs multiple SDK instances within the same workspace, their requests count against the same limit.

Error responses

All error responses use a consistent JSON structure:

{
  "ok": false,
  "error": {
    "code": "error_code",
    "message": "Human-readable description"
  }
}

Status	Error code	Description
`400`	`invalid_json`	The request body is not valid JSON
`400`	`validation_error`	The payload is valid JSON but fails schema validation
`401`	`unauthorized`	The API key is missing, malformed, or has been revoked
`402`	`monthly_limit_reached`	The workspace has reached its monthly event limit
`402`	`feature_not_available`	The requested feature (e.g. lineage) requires a higher plan tier
`429`	`rate_limit_exceeded`	You have exceeded the rate limit for this workspace
`500`	`internal_error`	An unexpected error occurred on TraceStax’s servers
`503`	`service_unavailable`	The event could not be queued; retry the request

429 responses include a Retry-After header indicating the number of seconds to wait before retrying:

HTTP/1.1 429 Too Many Requests
Retry-After: 12

Retry guidance

The TraceStax SDKs automatically retry failed requests using exponential backoff:

Retried conditions: 429, 500, 502, 503, 504, and network-level errors (connection reset, timeout)
Not retried: 400, 401, 402 — these indicate a problem with the payload itself or plan limits that a retry will not fix
Attempts: up to 3 total (initial attempt + 2 retries)
Backoff: 1 second x 2^(attempt - 1) with +/-20% jitter — so approximately 1 s, 2 s on successive retries

If all retries are exhausted, the SDK drops the events and logs a warning. Events are not buffered to disk.