v3

latestOpenAPI 3.1.02026-07-311,4541,5202.3 MB
experiments

Retrieve Experiment Span

Retrieve single experiment trace with full span tree, or submit workflow result.

GET /evaluations/experiments/<experiment_id>/logs/<trace_unique_id>/ Returns:

  • Trace-level aggregated metrics (cost, tokens, duration, etc.)
  • Full hierarchical span tree with all children
  • Enriched with storage (input/output) for API key authentication
  • Complete scores (LLM evaluator + human annotation) with evaluator metadata

PATCH /evaluations/experiments/<experiment_id>/logs/<trace_unique_id>/ Body: {"input": {...}, "output": {...}, "metrics": {...}, "metadata": {...}} Purpose: Submit wait-task workflow result via resume mechanism

  • Uses get_full_object_by_unique_id for cached retrieval (performance optimized)
  • Supports both JWT and API key authentication
  • Partial updates with existing data merging
  • Creates workflow spans in unified format with proper trace hierarchy
  • Triggers evaluators if specified in experiment configuration
  • Input/output can be any JSON type (dict, list, string, number, boolean)

Note: The URL parameter is called 'log_id' but it should be the trace_unique_id. This returns a full TRACE (aggregated) with span tree, not a single log/span. The 'id' field in the list endpoint exposes trace_unique_id for use in detail/PATCH operations.

Uses SpanTreeSerializerContextMixin to automatically handle:

  • Span tree inclusion (always enabled for detail view)
  • Storage enrichment based on authentication type (JWT vs API key)
  • Dynamic serializer configuration

Uses DataEnrichmentMixin to enrich scores with:

  • Human annotation scores from Postgres EvalResult
  • Evaluator metadata (name, slug, score_value_type)
  • All score types (numerical, boolean, string, categorical, json)
get/api/v2/experiments/{experiment_id}/logs/{log_id}/

Path parameters

experiment_idstring required
log_idstring required

Headers

Authorizationstring required

Use your Respan API key for Respan API authentication. Enter only the Respan API key value; clients send Authorization: Bearer <RESPAN_API_KEY>. For /api/responses, provider credentials such as Perplexity, OpenAI, or Azure OpenAI go in Settings -> Providers or respan_params.credential_override in the request body, not in this authentication field.

Response

idstring required
trace_unique_idstring required
root_span_unique_idstring
unique_organization_idstring
environmentstring
customer_identifierstring
start_timestring date-time
end_timestring date-time
durationnumber double
span_countinteger
llm_call_countinteger
total_costnumber double
total_prompt_tokensinteger
total_completion_tokensinteger
total_tokensinteger
error_countinteger
namestring
inputstring
outputstring
storage_object_keystring
comparison_keystring
statusstring
expected_outputstring
updated_storage_object_keystring
latencynumber double
scoresstring required
span_treestring required