PATCH
/
spans
/
{span_id}
Python
from datetime import datetime, timezone
from opperai import Opper
import time

opper = Opper(http_bearer="YOUR_API_KEY")

# First, create a span to have a real span_id to work with
created_span = opper.spans.create(
    name="ml_deployment_research",
    start_time=datetime.now(timezone.utc),
    type="research",
    input="What are the best practices for machine learning deployment?",
    meta={
        "user_id": "user_123",
        "session_id": "session_456",
        "research_type": "deployment",
    },
)

print(f"Created span with ID: {created_span.id}")

# Update span with completion status and results
completed_span = opper.spans.update(
    span_id=created_span.id,
    end_time=datetime.now(timezone.utc),
    output="Here are the best practices for ML deployment: 1) Use containerization 2) Implement proper monitoring 3) Version your models...",
    score=9,
    meta={
        "completion_status": "success",
        "tokens_used": 1250,
        "model_version": "gpt-4o",
        "retrieval_docs_count": 5,
    },
)

print(f"Updated span: {completed_span.name}")
print(f"Output length: {len(completed_span.output)} characters")
print(f"Score: {completed_span.score}")
print(f"Status: Completed")

# Example: Update span with error status
try:
    # Simulate an error scenario with a new span
    error_span_created = opper.spans.create(
        name="ml_deployment_research_v2",
        start_time=datetime.now(timezone.utc),
        type="research",
        input="What are the best practices for ML model versioning?",
        meta={
            "user_id": "user_123",
            "session_id": "session_456",
            "research_type": "versioning",
        },
    )

    error_span = opper.spans.update(
        span_id=error_span_created.id,
        end_time=datetime.now(timezone.utc),
        error="Connection timeout to knowledge base after 30 seconds",
        meta={"completion_status": "error", "error_type": "timeout", "retry_count": 3},
    )
    print(f"\nError span updated: {error_span.error}")
except Exception as e:
    print(f"Failed to update span: {e}")
{
  "name": "my span",
  "start_time": "2024-03-20T10:00:00+00:00",
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "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": "<any>",
  "output": "<any>",
  "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.

Path Parameters

span_id
string<uuid>
required

The ID of the span to update

Body

application/json

The span to update

name
string | null

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

Examples:

"my span"

start_time
string<date-time> | null

The start time of the span in UTC

Examples:

"2025-09-02T11:28:28.329917Z"

type
string | null

The type of the span

Examples:

"email_tool"

end_time
string<date-time> | null

The end time of the span in UTC

Examples:

"2025-09-02T11:28:28.329979Z"

input
string | null

The input of the span

Examples:

"Hello, world!"

output
string | null

The output of the span

Examples:

"Hello, world!"

error
string | null

In case of an error, the error message

Examples:

"Exception: This is an error message"

meta
object | null

The meta data of the span

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

The score of the span

Examples:

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

Examples:

"my span"

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

The start time of the span in UTC

Examples:

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

trace_id
string<uuid> | null

The id of the trace

Examples:

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

parent_id
string<uuid> | null

The id of the parent span

Examples:

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

type
string | null

The type of the span

Examples:

"email_tool"

end_time
string<date-time> | null

The end time of the span in UTC

Examples:

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

input
any

The input of the span

output
any

The output of the span

error
string | null

In case of an error, the error message

Examples:

"Exception: This is an error message"

meta
object | null

The metadata of the span

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

The score of the span

Examples:

10