Tracing

For instructions on how to authenticate to use this endpoint, see API overview.

Endpoints

POST
POST
POST
GET
POST
GET
GET
POST
GET
PATCH
DELETE
← Previous page

Create tracing spans sparkline

Required API key scopes

tracing:read

Request parameters

  • query

Response


Example request

POST /api/projects/:project_id/tracing/spans/sparkline
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/tracing/spans/sparkline/\
	-d query=undefined

Example response

Status 200
RESPONSE
{
  "results": [
    {
      "time": "2019-08-24T14:15:22Z",
      "service": "string",
      "count": 0
    }
  ]
}

Create tracing spans symbol stats

Required API key scopes

tracing:read

Request parameters

  • query

Response


Example request

POST /api/projects/:project_id/tracing/spans/symbol-stats
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/tracing/spans/symbol-stats/\
	-d query=undefined

Example response

Status 200
RESPONSE
{
  "results": [
    {
      "count": 0,
      "error_count": 0,
      "sum_duration_nano": 0.1,
      "p50_duration_nano": 0.1,
      "p95_duration_nano": 0.1,
      "p99_duration_nano": 0.1,
      "busy_count": 0,
      "p50_busy_nano": 0.1,
      "p95_busy_nano": 0.1,
      "p99_busy_nano": 0.1,
      "line": 0,
      "name": "string",
      "end_line": 0,
      "previous": {
        "count": 0,
        "error_count": 0,
        "sum_duration_nano": 0.1,
        "p50_duration_nano": 0.1,
        "p95_duration_nano": 0.1,
        "p99_duration_nano": 0.1,
        "busy_count": 0,
        "p50_busy_nano": 0.1,
        "p95_busy_nano": 0.1,
        "p99_busy_nano": 0.1
      },
      "count_pct_change": 0,
      "p95_duration_pct_change": 0
    }
  ],
  "granularity": "line"
}

Create tracing spans trace

Required API key scopes

tracing:read

Path parameters

  • trace_id
    string

Request parameters

  • dateRange
  • excludeAttributes
    boolean
    Default: false
  • offset
    integer

Response


Example request

POST /api/projects/:project_id/tracing/spans/trace/:trace_id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/tracing/spans/trace/:trace_id/\
	-d dateRange=undefined

Example response

Status 200
RESPONSE
{
  "results": [
    {
      "uuid": "string",
      "trace_id": "string",
      "span_id": "string",
      "parent_span_id": "string",
      "name": "string",
      "kind": 0,
      "service_name": "string",
      "status_code": 0,
      "timestamp": "2019-08-24T14:15:22Z",
      "end_time": "2019-08-24T14:15:22Z",
      "duration_nano": 0.1,
      "is_root_span": true,
      "matched_filter": 0,
      "trace_start": "2019-08-24T14:15:22Z",
      "trace_duration": 0.1,
      "attributes": {
        "property1": "string",
        "property2": "string"
      },
      "resource_attributes": {
        "property1": "string",
        "property2": "string"
      },
      "self_time_nano": 0.1
    }
  ],
  "hasMore": true,
  "nextOffset": 0
}

Retrieve tracing spans trace ai events

List the LLM analytics events whose $ai_trace_id is this trace's id, so the waterfall can show each model call inline with the spans.

The spans and the AI events live on different ClickHouse clusters, so one query cannot join them; this returns the events half and the caller places them by time.

Required API key scopes

tracing:readllm_analytics:read

Path parameters

  • trace_id
    string

Response


Example request

GET /api/projects/:project_id/tracing/spans/trace/:trace_id/ai_events
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/tracing/spans/trace/:trace_id/ai_events/

Example response

Status 200
RESPONSE
{
  "results": [
    {
      "uuid": "string",
      "event": "string",
      "started_at": "2019-08-24T14:15:22Z",
      "ai_trace_id": "string",
      "ai_span_id": "string",
      "ai_parent_id": "string",
      "span_name": "string",
      "latency_seconds": 0,
      "model": "string",
      "provider": "string",
      "input_tokens": 0,
      "output_tokens": 0,
      "total_cost_usd": 0,
      "is_error": true
    }
  ],
  "limit": 0,
  "has_more": true
}

Create tracing spans tree

Required API key scopes

tracing:read

Request parameters

  • query

Response


Example request

POST /api/projects/:project_id/tracing/spans/tree
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/tracing/spans/tree/\
	-d query=undefined

Example response

Status 200
RESPONSE
{
  "results": [
    {
      "name": "string",
      "service_name": "string",
      "parent_name": "string",
      "parent_service": "string",
      "count": 0,
      "error_count": 0,
      "total_duration_nano": 0.1,
      "avg_duration_nano": 0.1,
      "p50_duration_nano": 0.1,
      "p95_duration_nano": 0.1,
      "p99_duration_nano": 0.1,
      "p999_duration_nano": 0.1,
      "avg_start_offset_nano": 0.1,
      "calls_per_parent_invocation": 0
    }
  ],
  "compare": [
    {
      "name": "string",
      "service_name": "string",
      "parent_name": "string",
      "parent_service": "string",
      "count": 0,
      "error_count": 0,
      "total_duration_nano": 0.1,
      "avg_duration_nano": 0.1,
      "p50_duration_nano": 0.1,
      "p95_duration_nano": 0.1,
      "p99_duration_nano": 0.1,
      "p999_duration_nano": 0.1,
      "avg_start_offset_nano": 0.1,
      "calls_per_parent_invocation": 0
    }
  ]
}

Retrieve tracing spans values

Required API key scopes

tracing:read

Query parameters

  • attribute_type
    string
    One of: "span""span_attribute""span_resource_attribute"
  • dateRange
    string
  • date_from
    string
  • date_to
    string
  • key
    string
  • limit
    integer
  • offset
    integer
  • value
    string

Example request

GET /api/projects/:project_id/tracing/spans/values
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/tracing/spans/values/

Example response

Status 200 No response body

List all tracing views

Required API key scopes

tracing:read

Query parameters

  • limit
    integer
  • offset
    integer

Response


Example request

GET /api/projects/:project_id/tracing/views
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/tracing/views/

Example response

Status 200
RESPONSE
{
  "count": 123,
  "next": "http://api.example.org/accounts/?offset=400&limit=100",
  "previous": "http://api.example.org/accounts/?offset=200&limit=100",
  "results": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "short_id": "string",
      "name": "string",
      "filters": {},
      "pinned": true,
      "created_at": "2019-08-24T14:15:22Z",
      "created_by": {
        "id": 0,
        "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
        "distinct_id": "string",
        "first_name": "string",
        "last_name": "string",
        "email": "user@example.com",
        "is_email_verified": true,
        "hedgehog_config": {},
        "role_at_organization": "engineering"
      },
      "updated_at": "2019-08-24T14:15:22Z"
    }
  ]
}

Create tracing views

Required API key scopes

tracing:write

Request parameters

  • name
    string
  • filters
    object
  • pinned
    boolean

Response


Example request

POST /api/projects/:project_id/tracing/views
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/tracing/views/\
	-d name="string"

Example response

Status 201
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "short_id": "string",
  "name": "string",
  "filters": {},
  "pinned": true,
  "created_at": "2019-08-24T14:15:22Z",
  "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {},
    "role_at_organization": "engineering"
  },
  "updated_at": "2019-08-24T14:15:22Z"
}

Retrieve tracing views

Required API key scopes

tracing:read

Path parameters

  • short_id
    string

Response


Example request

GET /api/projects/:project_id/tracing/views/:short_id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/tracing/views/:short_id/

Example response

Status 200
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "short_id": "string",
  "name": "string",
  "filters": {},
  "pinned": true,
  "created_at": "2019-08-24T14:15:22Z",
  "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {},
    "role_at_organization": "engineering"
  },
  "updated_at": "2019-08-24T14:15:22Z"
}

Update tracing views

Required API key scopes

tracing:write

Path parameters

  • short_id
    string

Request parameters

  • name
    string
  • filters
    object
  • pinned
    boolean

Response


Example request

PATCH /api/projects/:project_id/tracing/views/:short_id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl -X PATCH \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/tracing/views/:short_id/\
	-d name="string"

Example response

Status 200
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "short_id": "string",
  "name": "string",
  "filters": {},
  "pinned": true,
  "created_at": "2019-08-24T14:15:22Z",
  "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {},
    "role_at_organization": "engineering"
  },
  "updated_at": "2019-08-24T14:15:22Z"
}

Delete tracing views

Required API key scopes

tracing:write

Path parameters

  • short_id
    string

Example request

DELETE /api/projects/:project_id/tracing/views/:short_id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl  -X DELETE \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/tracing/views/:short_id/

Example response

Status 204 No response body
← Previous page