openapi: 3.0.3
info:
title: Arize-Phoenix REST annotation_configs spans API
description: Schema for Arize-Phoenix REST API
version: '1.0'
tags:
- name: spans
paths:
/v1/projects/{project_identifier}/spans/otlpv1:
get:
tags:
- spans
summary: Search spans with simple filters (no DSL)
description: Return spans within a project filtered by time range. Supports cursor-based pagination.
operationId: spanSearch
parameters:
- name: project_identifier
in: path
required: true
schema:
type: string
description: 'The project identifier: either project ID or project name. If using a project name, it cannot contain slash (/), question mark (?), or pound sign (#) characters.'
title: Project Identifier
description: 'The project identifier: either project ID or project name. If using a project name, it cannot contain slash (/), question mark (?), or pound sign (#) characters.'
- name: cursor
in: query
required: false
schema:
type: string
nullable: true
description: Pagination cursor (Span Global ID)
title: Cursor
description: Pagination cursor (Span Global ID)
- name: limit
in: query
required: false
schema:
type: integer
maximum: 1000
exclusiveMinimum: 0
description: Maximum number of spans to return
default: 100
title: Limit
description: Maximum number of spans to return
- name: start_time
in: query
required: false
schema:
type: string
format: date-time
nullable: true
description: Inclusive lower bound time
title: Start Time
description: Inclusive lower bound time
- name: end_time
in: query
required: false
schema:
type: string
format: date-time
nullable: true
description: Exclusive upper bound time
title: End Time
description: Exclusive upper bound time
- name: trace_id
in: query
required: false
schema:
type: array
items:
type: string
nullable: true
description: Filter by one or more trace IDs
title: Trace Id
description: Filter by one or more trace IDs
- name: parent_id
in: query
required: false
schema:
type: string
nullable: true
description: Filter by parent span ID. Use "null" to get root spans only.
title: Parent Id
description: Filter by parent span ID. Use "null" to get root spans only.
- name: name
in: query
required: false
schema:
type: array
items:
type: string
nullable: true
description: Filter by span name(s)
title: Name
description: Filter by span name(s)
- name: status_code
in: query
required: false
schema:
type: array
items:
type: string
nullable: true
description: 'Filter by status code(s). Values: OK, ERROR, UNSET'
title: Status Code
description: 'Filter by status code(s). Values: OK, ERROR, UNSET'
- name: attribute
in: query
required: false
schema:
type: array
items:
type: string
nullable: true
description: 'Filter spans by `key:value`. Key is a dot-path (e.g. `user.id`, `metadata.tier`). Value is JSON-parsed: `k:12345` is int, `k:true` is bool, otherwise string (`k:user-42`). To match a numeric- or boolean-looking STRING, JSON-quote it: `user.id:"12345"` (URL-encoded `%2212345%22`). Split is on the first `:` only, so values may contain colons (`session.id:sess:abc:123`, ISO timestamps). Repeat the param to AND filters. List-valued attributes (e.g. `tag.tags`) cannot be matched here. Returns 422 on malformed input (missing colon, empty key/value, or list/dict/null value).'
title: Attribute
description: 'Filter spans by `key:value`. Key is a dot-path (e.g. `user.id`, `metadata.tier`). Value is JSON-parsed: `k:12345` is int, `k:true` is bool, otherwise string (`k:user-42`). To match a numeric- or boolean-looking STRING, JSON-quote it: `user.id:"12345"` (URL-encoded `%2212345%22`). Split is on the first `:` only, so values may contain colons (`session.id:sess:abc:123`, ISO timestamps). Repeat the param to AND filters. List-valued attributes (e.g. `tag.tags`) cannot be matched here. Returns 422 on malformed input (missing colon, empty key/value, or list/dict/null value).'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/OtlpSpansResponseBody'
'403':
content:
text/plain:
schema:
type: string
description: Forbidden
'404':
content:
text/plain:
schema:
type: string
description: Not Found
'422':
content:
text/plain:
schema:
type: string
description: Unprocessable Entity
/v1/projects/{project_identifier}/spans:
get:
tags:
- spans
summary: List spans with simple filters (no DSL)
description: Return spans within a project filtered by time range. Supports cursor-based pagination.
operationId: getSpans
parameters:
- name: project_identifier
in: path
required: true
schema:
type: string
description: 'The project identifier: either project ID or project name. If using a project name, it cannot contain slash (/), question mark (?), or pound sign (#) characters.'
title: Project Identifier
description: 'The project identifier: either project ID or project name. If using a project name, it cannot contain slash (/), question mark (?), or pound sign (#) characters.'
- name: cursor
in: query
required: false
schema:
type: string
nullable: true
description: Pagination cursor (Span Global ID)
title: Cursor
description: Pagination cursor (Span Global ID)
- name: limit
in: query
required: false
schema:
type: integer
maximum: 1000
exclusiveMinimum: 0
description: Maximum number of spans to return
default: 100
title: Limit
description: Maximum number of spans to return
- name: start_time
in: query
required: false
schema:
type: string
format: date-time
nullable: true
description: Inclusive lower bound time
title: Start Time
description: Inclusive lower bound time
- name: end_time
in: query
required: false
schema:
type: string
format: date-time
nullable: true
description: Exclusive upper bound time
title: End Time
description: Exclusive upper bound time
- name: trace_id
in: query
required: false
schema:
type: array
items:
type: string
nullable: true
description: Filter by one or more trace IDs
title: Trace Id
description: Filter by one or more trace IDs
- name: parent_id
in: query
required: false
schema:
type: string
nullable: true
description: Filter by parent span ID. Use "null" to get root spans only.
title: Parent Id
description: Filter by parent span ID. Use "null" to get root spans only.
- name: name
in: query
required: false
schema:
type: array
items:
type: string
nullable: true
description: Filter by span name(s)
title: Name
description: Filter by span name(s)
- name: span_kind
in: query
required: false
schema:
type: array
items:
type: string
nullable: true
description: 'Filter by span kind(s). Values: LLM, CHAIN, TOOL, RETRIEVER, EMBEDDING, AGENT, RERANKER, GUARDRAIL, EVALUATOR, UNKNOWN'
title: Span Kind
description: 'Filter by span kind(s). Values: LLM, CHAIN, TOOL, RETRIEVER, EMBEDDING, AGENT, RERANKER, GUARDRAIL, EVALUATOR, UNKNOWN'
- name: status_code
in: query
required: false
schema:
type: array
items:
type: string
nullable: true
description: 'Filter by status code(s). Values: OK, ERROR, UNSET'
title: Status Code
description: 'Filter by status code(s). Values: OK, ERROR, UNSET'
- name: attribute
in: query
required: false
schema:
type: array
items:
type: string
nullable: true
description: 'Filter spans by `key:value`. Key is a dot-path (e.g. `user.id`, `metadata.tier`). Value is JSON-parsed: `k:12345` is int, `k:true` is bool, otherwise string (`k:user-42`). To match a numeric- or boolean-looking STRING, JSON-quote it: `user.id:"12345"` (URL-encoded `%2212345%22`). Split is on the first `:` only, so values may contain colons (`session.id:sess:abc:123`, ISO timestamps). Repeat the param to AND filters. List-valued attributes (e.g. `tag.tags`) cannot be matched here. Returns 422 on malformed input (missing colon, empty key/value, or list/dict/null value).'
title: Attribute
description: 'Filter spans by `key:value`. Key is a dot-path (e.g. `user.id`, `metadata.tier`). Value is JSON-parsed: `k:12345` is int, `k:true` is bool, otherwise string (`k:user-42`). To match a numeric- or boolean-looking STRING, JSON-quote it: `user.id:"12345"` (URL-encoded `%2212345%22`). Split is on the first `:` only, so values may contain colons (`session.id:sess:abc:123`, ISO timestamps). Repeat the param to AND filters. List-valued attributes (e.g. `tag.tags`) cannot be matched here. Returns 422 on malformed input (missing colon, empty key/value, or list/dict/null value).'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/SpansResponseBody'
'403':
content:
text/plain:
schema:
type: string
description: Forbidden
'404':
content:
text/plain:
schema:
type: string
description: Not Found
'422':
content:
text/plain:
schema:
type: string
description: Unprocessable Entity
post:
tags:
- spans
summary: Create spans
description: Submit spans to be inserted into a project. If any spans are invalid or duplicates, no spans will be inserted.
operationId: createSpans
parameters:
- name: project_identifier
in: path
required: true
schema:
type: string
description: 'The project identifier: either project ID or project name. If using a project name, it cannot contain slash (/), question mark (?), or pound sign (#) characters.'
title: Project Identifier
description: 'The project identifier: either project ID or project name. If using a project name, it cannot contain slash (/), question mark (?), or pound sign (#) characters.'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateSpansRequestBody'
responses:
'202':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/CreateSpansResponseBody'
'403':
content:
text/plain:
schema:
type: string
description: Forbidden
'404':
content:
text/plain:
schema:
type: string
description: Not Found
'400':
content:
text/plain:
schema:
type: string
description: Bad Request
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/span_annotations:
post:
tags:
- spans
summary: Create span annotations
operationId: annotateSpans
parameters:
- name: sync
in: query
required: false
schema:
type: boolean
description: If true, fulfill request synchronously.
default: false
title: Sync
description: If true, fulfill request synchronously.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AnnotateSpansRequestBody'
responses:
'200':
description: Span annotations inserted successfully
content:
application/json:
schema:
$ref: '#/components/schemas/AnnotateSpansResponseBody'
'403':
content:
text/plain:
schema:
type: string
description: Forbidden
'404':
content:
text/plain:
schema:
type: string
description: Span not found
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/span_notes:
post:
tags:
- spans
summary: Create a span note
description: Add a note annotation to a span. By default each call appends a new note with an auto-generated UUIDv4 identifier, so multiple notes accumulate on the same span. Callers may supply a non-empty `identifier` to upsert on (span_id, name='note', identifier) — repeated calls with the same identifier overwrite the existing note, matching the semantics of structured annotations.
operationId: createSpanNote
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateSpanNoteRequestBody'
required: true
responses:
'200':
description: Span note created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/CreateSpanNoteResponseBody'
'403':
description: Forbidden
content:
text/plain:
schema:
type: string
'404':
description: Span not found
content:
text/plain:
schema:
type: string
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/spans/{span_identifier}:
delete:
tags:
- spans
summary: Delete a span by span_identifier
description: "Delete a single span by identifier.\n\n **Important**: This operation deletes ONLY the specified span itself and does NOT\n delete its descendants/children. All child spans will remain in the trace and\n become orphaned (their parent_id will point to a non-existent span).\n\n Behavior:\n - Deletes only the target span (preserves all descendant spans)\n - If this was the last span in the trace, the trace record is also deleted\n - If the deleted span had a parent, its cumulative metrics (error count, token counts)\n are subtracted from all ancestor spans in the chain\n\n **Note**: This operation is irreversible and may create orphaned spans."
operationId: deleteSpan
parameters:
- name: span_identifier
in: path
required: true
schema:
type: string
description: 'The span identifier: either a relay GlobalID or OpenTelemetry span_id'
title: Span Identifier
description: 'The span identifier: either a relay GlobalID or OpenTelemetry span_id'
responses:
'204':
description: Successful Response
'403':
content:
text/plain:
schema:
type: string
description: Forbidden
'404':
content:
text/plain:
schema:
type: string
description: Not Found
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/document_annotations:
post:
tags:
- spans
summary: Annotate Span Documents
operationId: annotateSpanDocuments
parameters:
- name: sync
in: query
required: false
schema:
type: boolean
description: If set to true, the annotations are inserted synchronously.
default: false
title: Sync
description: If set to true, the annotations are inserted synchronously.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AnnotateSpanDocumentsRequestBody'
responses:
'200':
description: Span document annotation inserted successfully
content:
application/json:
schema:
$ref: '#/components/schemas/AnnotateSpanDocumentsResponseBody'
'403':
content:
text/plain:
schema:
type: string
description: Forbidden
'404':
content:
text/plain:
schema:
type: string
description: Span not found
'422':
content:
text/plain:
schema:
type: string
description: Invalid request - non-empty identifier not supported
components:
schemas:
OtlpEvent:
properties:
attributes:
items:
$ref: '#/components/schemas/OtlpKeyValue'
type: array
nullable: true
title: Attributes
description: attributes is a collection of attribute key/value pairs on the event. Attribute keys MUST be unique (it is not allowed to have more than one attribute with the same key).
dropped_attributes_count:
type: integer
maximum: 4294967295.0
minimum: 0.0
nullable: true
title: Dropped Attributes Count
description: dropped_attributes_count is the number of dropped attributes. If the value is 0, then no attributes were dropped.
name:
type: string
nullable: true
title: Name
description: name of the event. This field is semantically required to be set to non-empty string.
time_unix_nano:
anyOf:
- type: integer
exclusiveMaximum: 1.8446744073709552e+19
minimum: 0.0
- type: string
pattern: ^[0-9]+$
- type: 'null'
title: Time Unix Nano
description: time_unix_nano is the time the event occurred. Value is UNIX Epoch time in nanoseconds since 00:00:00 UTC on 1 January 1970.
additionalProperties: false
type: object
title: OtlpEvent
AnnotationResult:
properties:
label:
type: string
nullable: true
title: Label
description: The label assigned by the annotation
score:
type: number
nullable: true
title: Score
description: The score assigned by the annotation
explanation:
type: string
nullable: true
title: Explanation
description: Explanation of the annotation result
type: object
title: AnnotationResult
InsertedSpanDocumentAnnotation:
properties:
id:
type: string
title: Id
description: The ID of the inserted span document annotation
type: object
required:
- id
title: InsertedSpanDocumentAnnotation
SpanContext:
properties:
trace_id:
type: string
title: Trace Id
description: OpenTelemetry trace ID
span_id:
type: string
title: Span Id
description: OpenTelemetry span ID
type: object
required:
- trace_id
- span_id
title: SpanContext
examples:
- span_id: 1a2b3c4d5e6f7a8b
trace_id: a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
AnnotateSpansResponseBody:
properties:
data:
items:
$ref: '#/components/schemas/InsertedSpanAnnotation'
type: array
title: Data
type: object
required:
- data
title: AnnotateSpansResponseBody
AnnotateSpanDocumentsResponseBody:
properties:
data:
items:
$ref: '#/components/schemas/InsertedSpanDocumentAnnotation'
type: array
title: Data
type: object
required:
- data
title: AnnotateSpanDocumentsResponseBody
Span:
properties:
id:
type: string
title: Id
description: Span Global ID, distinct from the OpenTelemetry span ID
default: ''
name:
type: string
title: Name
description: Name of the span operation
context:
$ref: '#/components/schemas/SpanContext'
description: Span context containing trace_id and span_id
span_kind:
type: string
title: Span Kind
description: Type of work that the span encapsulates
parent_id:
type: string
nullable: true
title: Parent Id
description: OpenTelemetry span ID of the parent span
start_time:
type: string
format: date-time
title: Start Time
description: Start time of the span (must be timezone-aware)
end_time:
type: string
format: date-time
title: End Time
description: End time of the span (must be timezone-aware)
status_code:
type: string
title: Status Code
description: Status code of the span
status_message:
type: string
title: Status Message
description: Status message
default: ''
attributes:
additionalProperties: true
type: object
title: Attributes
description: Span attributes
events:
items:
$ref: '#/components/schemas/SpanEvent'
type: array
title: Events
description: Span events
type: object
required:
- name
- context
- span_kind
- start_time
- end_time
- status_code
title: Span
examples:
- attributes:
llm.model_name: gpt-4
llm.token_count.completion: 50
llm.token_count.prompt: 100
context:
span_id: 1a2b3c4d5e6f7a8b
trace_id: a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4
end_time: '2024-01-01T12:00:01Z'
events: []
name: llm_call
span_kind: LLM
start_time: '2024-01-01T12:00:00Z'
status_code: OK
status_message: ''
OtlpAnyValue:
properties:
array_value:
$ref: '#/components/schemas/OtlpArrayValue'
nullable: true
bool_value:
type: boolean
nullable: true
title: Bool Value
bytes_value:
type: string
pattern: ^[A-Za-z0-9+/]*={0,2}$
nullable: true
title: Bytes Value
double_value:
anyOf:
- type: number
- $ref: '#/components/schemas/OtlpDoubleValue'
- type: string
- type: 'null'
title: Double Value
int_value:
anyOf:
- type: integer
exclusiveMaximum: 9.223372036854776e+18
minimum: -9.223372036854776e+18
- type: string
pattern: ^-?[0-9]+$
- type: 'null'
title: Int Value
kvlist_value:
type: 'null'
title: Kvlist Value
string_value:
type: string
nullable: true
title: String Value
additionalProperties: false
type: object
title: OtlpAnyValue
SpansResponseBody:
properties:
data:
items:
$ref: '#/components/schemas/Span'
type: array
title: Data
next_cursor:
type: string
nullable: true
title: Next Cursor
type: object
required:
- data
- next_cursor
title: SpansResponseBody
OtlpKeyValue:
properties:
key:
type: string
nullable: true
title: Key
value:
$ref: '#/components/schemas/OtlpAnyValue'
nullable: true
additionalProperties: false
type: object
title: OtlpKeyValue
OtlpSpan:
properties:
attributes:
items:
$ref: '#/components/schemas/OtlpKeyValue'
type: array
nullable: true
title: Attributes
description: "attributes is a collection of key/value pairs. Note, global attributes like server name can be set using the resource API. Examples of attributes:\n\n \"/http/user_agent\": \"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/71.0.3578.98 Safari/537.36\"\n \"/http/server_latency\": 300\n \"example.com/myattribute\": true\n \"example.com/score\": 10.239\n\nThe OpenTelemetry API specification further restricts the allowed value types:\nhttps://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/common/README.md#attribute\nAttribute keys MUST be unique (it is not allowed to have more than one attribute with the same key)."
dropped_attributes_count:
type: integer
maximum: 4294967295.0
minimum: 0.0
nullable: true
title: Dropped Attributes Count
description: dropped_attributes_count is the number of attributes that were discarded. Attributes can be discarded because their keys are too long or because there are too many attributes. If this value is 0, then no attributes were dropped.
dropped_events_count:
type: integer
maximum: 4294967295.0
minimum: 0.0
nullable: true
title: Dropped Events Count
description: dropped_events_count is the number of dropped events. If the value is 0, then no events were dropped.
dropped_links_count:
type: integer
maximum: 4294967295.0
minimum: 0.0
nullable: true
title: Dropped Links Count
description: dropped_links_count is the number of dropped links after the maximum size was enforced. If this value is 0, then no links were dropped.
end_time_unix_nano:
anyOf:
- type: integer
exclusiveMaximum: 1.8446744073709552e+19
minimum: 0.0
- type: string
pattern: ^[0-9]+$
- type: 'null'
title: End Time Unix Nano
description: 'end_time_unix_nano is the end time of the span. On the client side, this is the time kept by the local machine where the span execution ends. On the server side, this is the time when the server application handler stops running.
Value is UNIX Epoch time in nanoseconds since 00:00:00 UTC on 1 January 1970.
This field is semantically required and it is expected that end_time >= start_time.'
events:
items:
$ref: '#/components/schemas/OtlpEvent'
type: array
nullable: true
title: Events
description: events is a collection of Event items. A span with no events is valid.
flags:
type: integer
maximum: 4294967295.0
minimum: 0.0
nullable: true
title: Flags
description: 'Flags, a bit field.
Bits 0-7 (8 least significant bits) are the trace flags as defined in W3C Trace Context specification. To read the 8-bit W3C trace flag, use `flags & SPAN_FLAGS_TRACE_FLAGS_MASK`.
See https://www.w3.org/TR/trace-context-2/#trace-flags for the flag definitions.
Bits 8 and 9 represent the 3 states of whether a span''s parent is remote. The states are (unknown, is not remote, is remote).
To read whether the value is known, use `(flags & SPAN_FLAGS_CONTEXT_HAS_IS_REMOTE_MASK) != 0`.
To read whether the span is remote, use `(flags & SPAN_FLAGS_CONTEXT_IS_REMOTE_MASK) != 0`.
When creating span messages, if the message is logically forwarded from another source with an equivalent flags fields (i.e., usually another OTLP span message), the field SHOULD be copied as-is. If creating from a source that does not have an equivalent flags field (such as a runtime representation of an OpenTelemetry span), the high 22 bits MUST be set to zero.
Readers MUST NOT assume that bits 10-31 (22 most significant bits) will be zero.
[Optional].'
kind:
anyOf:
- $ref: '#/components/schemas/OtlpKind'
- type: integer
maximum: 2147483647.0
minimum: -2147483648.0
- type: 'null'
title: Kind
description: Distinguishes between spans generated in a particular context. For example, two spans with the same name may be distinguished using `CLIENT` (caller) and `SERVER` (callee) to identify queueing latency associated with the span.
default: SPAN_KIND_INTERNAL
links:
type: 'null'
title: Links
name:
type: string
nullable: true
title: Name
description: 'A description of the span''s operation.
For example, the name can be a qualified method name or a file name and a line number where the operation is called. A best practice is to use the same display name at the same call point in an application. This makes it easier to correlate spans in different traces.
This field is semantically required to be set to non-empty string. Empty value is equivalent to an unknown span name.
This field is required.'
parent_span_id:
type: string
pattern: ^[A-Za-z0-9+/]*={0,2}$
nullable: true
title: Parent Span Id
description: The `span_id` of this span's parent span. If this is a root span, then this field must be empty. The ID is an 8-byte array.
span_id:
type: string
pattern: ^[A-Za-z0-9+/]*={0,2}$
nullable: true
title: Span Id
description: 'A unique identifier for a span within a trace, assigned when the span is created. The ID is an 8-byte array. An ID with all zeroes OR of length other than 8 bytes is considered invalid (empty string in OTLP/JSON is zero-length and thus is also invalid).
This field is required.'
start_time_unix_nano:
anyOf:
- type: integer
exclusiveMaximum: 1.8446744073709552e+19
minimum: 0.0
- type: string
pattern: ^[0-9]+$
- type: 'null'
title: Start Time Unix Nano
description: 'start_time_uni
# --- truncated at 32 KB (41 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/phoenix/refs/heads/main/openapi/phoenix-spans-api-openapi.yml