Skip to main content

​
Ingest Traces

Send performance traces to Pulse via the API.

​
Single Trace

POST /api/v1/traces

​
Request

curl https://pulse.brainzlab.ai/api/v1/traces \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "trace_id": "abc123",
    "name": "GET /users",
    "kind": "request",
    "started_at": "2024-01-15T10:30:00.000Z",
    "ended_at": "2024-01-15T10:30:00.245Z",
    "request_method": "GET",
    "request_path": "/users",
    "controller": "UsersController",
    "action": "index",
    "status": 200,
    "environment": "production",
    "commit": "abc123",
    "host": "web-1"
  }'

​
Parameters

FieldTypeRequiredDescription
trace_idstringNoUnique trace ID (auto-generated if not provided)
namestringYesTrace name (e.g., “GET /users”)
kindstringYesType: request, job, custom
started_atstringYesISO8601 start timestamp
ended_atstringYesISO8601 end timestamp
request_methodstringNoHTTP method
request_pathstringNoRequest path
controllerstringNoController name
actionstringNoAction name
statusintegerNoHTTP status code
environmentstringNoEnvironment (production, staging, etc.)
commitstringNoGit commit SHA
hoststringNoServer hostname
user_idstringNoUser identifier
errorbooleanNoWhether request errored
error_classstringNoError class name
error_messagestringNoError message
spansarrayNoChild spans (see below)

​
Response

{
  "data": {
    "id": "trace_abc123",
    "trace_id": "abc123",
    "name": "GET /users",
    "duration_ms": 245,
    "status": 200
  }
}

​
With Spans

Include child spans for detailed breakdown: 
curl https://pulse.brainzlab.ai/api/v1/traces \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "trace_id": "abc123",
    "name": "GET /users/123",
    "kind": "request",
    "started_at": "2024-01-15T10:30:00.000Z",
    "ended_at": "2024-01-15T10:30:00.245Z",
    "request_method": "GET",
    "request_path": "/users/123",
    "status": 200,
    "spans": [
      {
        "span_id": "span_1",
        "name": "User.find",
        "kind": "db",
        "started_at": "2024-01-15T10:30:00.010Z",
        "ended_at": "2024-01-15T10:30:00.015Z",
        "data": {
          "sql": "SELECT * FROM users WHERE id = $1",
          "table": "users"
        }
      },
      {
        "span_id": "span_2",
        "name": "Redis GET",
        "kind": "cache",
        "started_at": "2024-01-15T10:30:00.016Z",
        "ended_at": "2024-01-15T10:30:00.017Z",
        "data": {
          "command": "GET",
          "key": "user:123:settings"
        }
      },
      {
        "span_id": "span_3",
        "name": "render show.html.erb",
        "kind": "view",
        "started_at": "2024-01-15T10:30:00.020Z",
        "ended_at": "2024-01-15T10:30:00.240Z"
      }
    ]
  }'

​
Span Parameters

FieldTypeRequiredDescription
span_idstringNoUnique span ID
parent_span_idstringNoParent span ID for nesting
namestringYesSpan name
kindstringYesType: db, cache, http, view, job, custom
started_atstringYesISO8601 start timestamp
ended_atstringYesISO8601 end timestamp
dataobjectNoAdditional span data

​
Bulk Ingest

Send multiple traces in one request: 
POST /api/v1/traces/batch

​
Request

curl https://pulse.brainzlab.ai/api/v1/traces/batch \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "traces": [
      {
        "name": "GET /users",
        "kind": "request",
        "started_at": "2024-01-15T10:30:00.000Z",
        "ended_at": "2024-01-15T10:30:00.100Z",
        "status": 200
      },
      {
        "name": "POST /orders",
        "kind": "request",
        "started_at": "2024-01-15T10:30:01.000Z",
        "ended_at": "2024-01-15T10:30:01.500Z",
        "status": 201
      }
    ]
  }'

​
Response

{
  "data": {
    "accepted": 2,
    "rejected": 0
  }
}

​
Job Traces

Track background job execution: 
{
  "trace_id": "job_abc123",
  "name": "ProcessOrderJob",
  "kind": "job",
  "started_at": "2024-01-15T10:30:00.000Z",
  "ended_at": "2024-01-15T10:30:02.500Z",
  "job_class": "ProcessOrderJob",
  "job_id": "abc123",
  "queue": "default",
  "environment": "production",
  "data": {
    "arguments": ["order_123"],
    "executions": 1
  }
}

​
Rate Limits

  • Single trace: Standard rate limit
  • Batch: 10 requests/minute, up to 500 traces per request

​
Errors

CodeDescription
invalid_kindKind must be request/job/custom
missing_timestampsstarted_at and ended_at required
invalid_timestampsended_at must be after started_at
batch_too_largeBatch exceeds 500 traces