Spans

REST API methods for interacting with Phoenix spans

Create span annotations

post

Query parameters

syncbooleanOptional

If true, fulfill request synchronously.

Default: false

Body

Responses

200

Span annotations inserted successfully

application/json

403

Forbidden

text/plain

404

Span not found

text/plain

422

Validation Error

application/json

post

HTTPcURLJavaScriptPython

POST /v1/span_annotations HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 189

{
  "data": [
    {
      "span_id": "text",
      "name": "text",
      "annotator_kind": "LLM",
      "result": {
        "label": "text",
        "score": 1,
        "explanation": "text"
      },
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "identifier": ""
    }
  ]
}

{
  "data": [
    {
      "id": "text"
    }
  ]
}

List spans with simple filters (no DSL)

get

Return spans within a project filtered by time range. Supports cursor-based pagination.

Path parameters

project_identifierstringRequired

The project identifier: either project ID or project name. If using a project name, it cannot contain slash (/), question mark (?), or pound sign (#) characters.

Query parameters

cursorany ofOptional

Pagination cursor (Span Global ID)

stringOptional

or

nullOptional

limitinteger · max: 1000Optional

Maximum number of spans to return

Default: 100

start_timeany ofOptional

Inclusive lower bound time

string · date-timeOptional

or

nullOptional

end_timeany ofOptional

Exclusive upper bound time

string · date-timeOptional

or

nullOptional

Responses

200

Successful Response

application/json

403

Forbidden

text/plain

404

Not Found

text/plain

422

Unprocessable Entity

text/plain

get

HTTPcURLJavaScriptPython

GET /v1/projects/{project_identifier}/spans HTTP/1.1
Host: 
Accept: */*

{
  "data": [
    {
      "id": "",
      "name": "text",
      "context": {
        "trace_id": "text",
        "span_id": "text"
      },
      "span_kind": "text",
      "parent_id": "text",
      "start_time": "2025-07-20T17:17:39.137Z",
      "end_time": "2025-07-20T17:17:39.137Z",
      "status_code": "text",
      "status_message": "",
      "attributes": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "events": [
        {
          "name": "text",
          "timestamp": "2025-07-20T17:17:39.137Z",
          "attributes": {
            "ANY_ADDITIONAL_PROPERTY": "anything"
          }
        }
      ]
    }
  ],
  "next_cursor": "text"
}

Search spans with simple filters (no DSL)

get

Return spans within a project filtered by time range. Supports cursor-based pagination.

Path parameters

project_identifierstringRequired

The project identifier: either project ID or project name. If using a project name, it cannot contain slash (/), question mark (?), or pound sign (#) characters.

Query parameters

cursorany ofOptional

Pagination cursor (Span Global ID)

stringOptional

or

nullOptional

limitinteger · max: 1000Optional

Maximum number of spans to return

Default: 100

start_timeany ofOptional

Inclusive lower bound time

string · date-timeOptional

or

nullOptional

end_timeany ofOptional

Exclusive upper bound time

string · date-timeOptional

or

nullOptional

Responses

200

Successful Response

application/json

403

Forbidden

text/plain

404

Not Found

text/plain

422

Unprocessable Entity

text/plain

get

HTTPcURLJavaScriptPython

GET /v1/projects/{project_identifier}/spans/otlpv1 HTTP/1.1
Host: 
Accept: */*

{
  "data": [
    {
      "attributes": [
        {
          "key": "text",
          "value": "[Circular Reference]"
        }
      ],
      "dropped_attributes_count": 1,
      "dropped_events_count": 1,
      "dropped_links_count": 1,
      "end_time_unix_nano": 1,
      "events": [
        {
          "attributes": "[Circular Reference]",
          "dropped_attributes_count": 1,
          "name": "text",
          "time_unix_nano": 1
        }
      ],
      "flags": 1,
      "kind": "SPAN_KIND_INTERNAL",
      "links": null,
      "name": "text",
      "parent_span_id": "text",
      "span_id": "text",
      "start_time_unix_nano": 1,
      "status": {
        "code": 1,
        "message": "text"
      },
      "trace_id": "text",
      "trace_state": "text"
    }
  ],
  "next_cursor": "text"
}