Skip to main content
POST
/
spans
Python
from datetime import datetime, timezone
from opperai import Opper

opper = Opper(http_bearer="YOUR_API_KEY")

# Create a parent span for a user workflow
parent_span = opper.spans.create(
    name="user_question_workflow",
    start_time=datetime.now(timezone.utc),
    type="workflow",
    input="What are the best practices for machine learning deployment?",
    meta={
        "user_id": "user_123",
        "session_id": "session_456",
        "workflow_version": "v2.1",
    },
)

print(f"Created parent span: {parent_span.name}")
print(f"Span ID: {parent_span.id}")
print(f"Trace ID: {parent_span.trace_id}")

# Create a child span for knowledge base lookup
child_span = opper.spans.create(
    name="knowledge_base_search",
    parent_id=parent_span.id,
    trace_id=parent_span.trace_id,
    type="retrieval",
    input="machine learning deployment best practices",
    meta={"search_type": "semantic", "kb_name": "ml_docs"},
)

print(f"\nCreated child span: {child_span.name}")
print(f"Parent span ID: {child_span.parent_id}")
print(f"Same trace ID: {child_span.trace_id}")
{
  "name": "<string>",
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "start_time": "2024-03-20T10:00:00+00:00",
  "trace_id": "123e4567-e89b-12d3-a456-426614174000",
  "parent_id": "123e4567-e89b-12d3-a456-426614174000",
  "type": "email_tool",
  "end_time": "2024-03-20T10:00:10+00:00",
  "input": "Hello, world!",
  "output": "Hello, world!",
  "error": "Exception: This is an error message",
  "meta": {
    "key": "value"
  },
  "score": 10
}

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

The definition of the span to create

name
string
required

The name of the span, something descriptive about the span that will be used to identify it when querying

start_time
string<date-time> | null

The start time of the span in UTC

Example:

"2024-03-20T10:00:00+00:00"

id
string<uuid> | null

The id of the span

Example:

"123e4567-e89b-12d3-a456-426614174000"

trace_id
string<uuid> | null

The id of the trace

Example:

"123e4567-e89b-12d3-a456-426614174000"

parent_id
string<uuid> | null

The id of the parent span

Example:

"123e4567-e89b-12d3-a456-426614174000"

type
string | null

The type of the span

Example:

"email_tool"

end_time
string<date-time> | null

The end time of the span in UTC

Example:

"2024-03-20T10:00:10+00:00"

input
any | null

The input of the span

Example:

"Hello, world!"

output
any | null

The output of the span

Example:

"Hello, world!"

error
string | null

In case of an error, the error message

Example:

"Exception: This is an error message"

meta
Meta · object

The metadata of the span

Example:
{ "key": "value" }
score
integer | null

The score of the span

Example:

10

Response

Successful Response

name
string
required

The name of the span, something descriptive about the span that will be used to identify it when querying

id
string<uuid>
required
start_time
string<date-time> | null

The start time of the span in UTC

Example:

"2024-03-20T10:00:00+00:00"

trace_id
string<uuid> | null

The id of the trace

Example:

"123e4567-e89b-12d3-a456-426614174000"

parent_id
string<uuid> | null

The id of the parent span

Example:

"123e4567-e89b-12d3-a456-426614174000"

type
string | null

The type of the span

Example:

"email_tool"

end_time
string<date-time> | null

The end time of the span in UTC

Example:

"2024-03-20T10:00:10+00:00"

input
any | null

The input of the span

Example:

"Hello, world!"

output
any | null

The output of the span

Example:

"Hello, world!"

error
string | null

In case of an error, the error message

Example:

"Exception: This is an error message"

meta
Meta · object

The metadata of the span

Example:
{ "key": "value" }
score
integer | null

The score of the span

Example:

10