Traces SDK Reference

Traces

Aggregate Traces

Aggregate trace metrics using the structured trace filter contract.

from orq_ai_sdk import Orq
import os

with Orq(
    api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:

    res = orq.traces.aggregate()

    # Handle response
    print(res)

import { Orq } from "@orq-ai/node";

const orq = new Orq({
  apiKey: process.env["ORQ_API_KEY"] ?? "",
});

async function run() {
  const result = await orq.traces.aggregate({});

  console.log(result);
}

run();

Show Parameters

{
    "from_": str,  # optional
    "to": str,  # optional
    "filters": [{  # optional
        "field": Optional[str],
        "op": Optional[str],
        "values": List[str],  # optional
    }],
    "group_by": List[str],  # optional
    "compute": [{  # optional
        "metric": Optional[str],
        "op": Optional[str],
    }],
    "limit": Optional[int],
    "filter_operator": Optional[str],
    "query": Optional[str],
}

{
  from?: Date;
  to?: Date;
  filters?: {
    field?: string;
    op?: string;
    values?: string[];
  }[];
  groupBy?: string[];
  compute?: {
    metric?: string;
    op?: string;
  }[];
  limit?: number;
  filterOperator?: string;
  query?: string;
}

Show Response

{
    "object": Optional[str],
    "data": [{  # optional
        "group": Dict[str, str],  # optional
        "metrics": Dict[str, float],  # optional
    }],
}

{
  object?: string;
  data?: {
    group?: Record<string, string>;
    metrics?: Record<string, number>;
  }[];
}

List trace fields that support facet value discovery.

from orq_ai_sdk import Orq
import os

with Orq(
    api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:

    res = orq.traces.list_facets()

    # Handle response
    print(res)

import { Orq } from "@orq-ai/node";

const orq = new Orq({
  apiKey: process.env["ORQ_API_KEY"] ?? "",
});

async function run() {
  const result = await orq.traces.listFacets();

  console.log(result);
}

run();

Show Response

{
    "data": [{  # optional
        "field": Optional[str],
        "label": Optional[str],
        "type": Optional[str],
    }],
}

{
  data?: {
    field?: string;
    label?: string;
    type?: string;
  }[];
}

List values and counts for one trace facet field.

from orq_ai_sdk import Orq
import os

with Orq(
    api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:

    res = orq.traces.list_facet_values(field="<value>")

    # Handle response
    print(res)

import { Orq } from "@orq-ai/node";

const orq = new Orq({
  apiKey: process.env["ORQ_API_KEY"] ?? "",
});

async function run() {
  const result = await orq.traces.listFacetValues({
    field: "<value>",
  });

  console.log(result);
}

run();

Show Parameters

{
    "field": str,  # required
    "from_": str,  # optional
    "to": str,  # optional
    "limit": Optional[int],
    "filter_operator": Optional[str],
}

{
  field: string;  // required
  from?: Date;
  to?: Date;
  limit?: number;
  filterOperator?: string;
}

Show Response

{
    "field": Optional[str],
    "values": [{  # optional
        "value": Optional[str],
        "count": Optional[int],
    }],
    "has_more": Optional[bool],
}

{
  field?: string;
  values?: {
    value?: string;
    count?: number;
  }[];
  hasMore?: boolean;
}

List Fields

List currently supported static trace fields.

from orq_ai_sdk import Orq
import os

with Orq(
    api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:

    res = orq.traces.list_fields()

    # Handle response
    print(res)

import { Orq } from "@orq-ai/node";

const orq = new Orq({
  apiKey: process.env["ORQ_API_KEY"] ?? "",
});

async function run() {
  const result = await orq.traces.listFields();

  console.log(result);
}

run();

Show Response

{
    "data": [{  # optional
        "name": Optional[str],
        "label": Optional[str],
        "type": Optional[str],
        "scope": Optional[str],
        "match": Optional[str],
        "operators": List[str],  # optional
        "facet": Optional[bool],
        "sortable": Optional[bool],
        "groupable": Optional[bool],
        "aliases": List[str],  # optional
        "enum_values": List[str],  # optional
    }],
}

{
  data?: {
    name?: string;
    label?: string;
    type?: string;
    scope?: string;
    match?: string;
    operators?: string[];
    facet?: boolean;
    sortable?: boolean;
    groupable?: boolean;
    aliases?: string[];
    enumValues?: string[];
  }[];
}

List Filters

List the evaluators, human reviews and metadata keys a trace filter can address.

from orq_ai_sdk import Orq
import os

with Orq(
    api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:

    res = orq.traces.list_filters()

    # Handle response
    print(res)

import { Orq } from "@orq-ai/node";

const orq = new Orq({
  apiKey: process.env["ORQ_API_KEY"] ?? "",
});

async function run() {
  const result = await orq.traces.listFilters();

  console.log(result);
}

run();

Show Parameters

{
    "include_all": Optional[bool],
}

{
  includeAll?: boolean;
}

Show Response

{
    "evaluators": [{  # optional
        "id": Optional[str],
        "display_name": Optional[str],
        "type": Optional[str],
        "output_type": Optional[str],
    }],
    "metadata": [{  # optional
        "key": Optional[str],
        "type": Optional[str],
    }],
    "annotations": [{  # optional
        "id": Optional[str],
        "display_name": Optional[str],
        "type": Optional[str],
        "option_values": List[str],  # optional
    }],
}

{
  evaluators?: {
    id?: string;
    displayName?: string;
    type?: string;
    outputType?: string;
  }[];
  metadata?: {
    key?: string;
    type?: string;
  }[];
  annotations?: {
    id?: string;
    displayName?: string;
    type?: string;
    optionValues?: string[];
  }[];
}

Query Traces

Run an OQL trace query over a time range. OQL selects the traces to return.

from orq_ai_sdk import Orq
from orq_ai_sdk.utils import parse_datetime
import os

with Orq(
    api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:

    res = orq.traces.query(from_=parse_datetime("2024-12-12T15:00:42.128Z"), to=parse_datetime("2025-02-10T08:55:05.233Z"), oql="<value>")

    # Handle response
    print(res)

import { Orq } from "@orq-ai/node";

const orq = new Orq({
  apiKey: process.env["ORQ_API_KEY"] ?? "",
});

async function run() {
  const result = await orq.traces.query({
    from: new Date("2024-12-12T15:00:42.128Z"),
    to: new Date("2025-02-10T08:55:05.233Z"),
    oql: "<value>",
  });

  console.log(result);
}

run();

Show Parameters

{
    "from_": str,  # required
    "to": str,  # required
    "oql": str,  # required
    "limit": Optional[int],
    "page_token": Optional[str],
}

{
  from: Date;  // required
  to: Date;  // required
  oql: string;  // required
  limit?: number;
  pageToken?: string;
}

Show Response

{
    "object": Optional[str],
    "search": {  # optional
        "object": Optional[Literal["list"]],
        "data": [{  # optional
            "object": Optional[Literal["trace"]],
            "trace_id": Optional[str],
            "root_span_id": Optional[str],
            "leading_span_id": Optional[str],
            "name": Optional[str],
            "operation": Optional[str],
            "status": Optional[str],
            "started_at": str,  # optional
            "ended_at": str,  # optional
            "duration_ms": Optional[float],
            "project_id": Optional[str],
            "identity_id": Optional[str],
            "session_id": Optional[str],
            "thread_id": Optional[str],
            "product": Optional[str],
            "providers": List[str],  # optional
            "models": List[str],  # optional
            "agent": {  # optional
                "id": Optional[str],
                "name": Optional[str],
            },
            "usage": {  # optional
                "prompt_tokens": Optional[int],
                "completion_tokens": Optional[int],
                "total_tokens": Optional[int],
                "prompt_cached_tokens": Optional[int],
                "prompt_audio_tokens": Optional[int],
                "completion_reasoning_tokens": Optional[int],
                "completion_audio_tokens": Optional[int],
                "completion_accepted_prediction_tokens": Optional[int],
                "completion_rejected_prediction_tokens": Optional[int],
                "prompt_cache_creation_tokens": Optional[int],
            },
            "cost": {  # optional
                "input": Optional[float],
                "output": Optional[float],
                "cache_read": Optional[float],
                "cache_write": Optional[float],
                "reasoning": Optional[float],
                "web_search": Optional[float],
                "total": Optional[float],
                "currency": Optional[str],
                "cached": Optional[float],
                "audio_input": Optional[float],
                "audio_output": Optional[float],
                "accepted_prediction": Optional[float],
                "rejected_prediction": Optional[float],
                "billable": Optional[bool],
                "pricing_tier": Optional[str],
                "threshold_exceeded": Optional[bool],
                "integration_id": Optional[str],
            },
            "id": Optional[str],
            "span_id": Optional[str],
            "parent_id": Optional[str],
            "type": Optional[str],
            "context": {  # optional
                "trace_id": Optional[str],
                "span_id": Optional[str],
            },
            "attributes": Dict[str, Any],  # optional
            "start_time": str,  # optional
            "end_time": str,  # optional
            "duration": Optional[float],
        }],
        "has_more": Optional[bool],
        "next_page_token": Optional[str],
        "meta": {  # optional
            "request_id": Optional[str],
            "from_": str,  # optional
            "to": str,  # optional
            "row_count": Optional[int],
        },
    },
}

{
  object?: string;
  search?: {
    object?: "list";
    data?: {
      object?: "trace";
      traceId?: string;
      rootSpanId?: string;
      leadingSpanId?: string;
      name?: string;
      operation?: string;
      status?: string;
      startedAt?: Date;
      endedAt?: Date;
      durationMs?: number;
      projectId?: string;
      identityId?: string;
      sessionId?: string;
      threadId?: string;
      product?: string;
      providers?: string[];
      models?: string[];
      agent?: {
        id?: string;
        name?: string;
      };
      usage?: {
        promptTokens?: number;
        completionTokens?: number;
        totalTokens?: number;
        promptCachedTokens?: number;
        promptAudioTokens?: number;
        completionReasoningTokens?: number;
        completionAudioTokens?: number;
        completionAcceptedPredictionTokens?: number;
        completionRejectedPredictionTokens?: number;
        promptCacheCreationTokens?: number;
      };
      cost?: {
        input?: number;
        output?: number;
        cacheRead?: number;
        cacheWrite?: number;
        reasoning?: number;
        webSearch?: number;
        total?: number;
        currency?: string;
        cached?: number;
        audioInput?: number;
        audioOutput?: number;
        acceptedPrediction?: number;
        rejectedPrediction?: number;
        billable?: boolean;
        pricingTier?: string;
        thresholdExceeded?: boolean;
        integrationId?: string;
      };
      id?: string;
      spanId?: string;
      parentId?: string;
      type?: string;
      context?: {
        traceId?: string;
        spanId?: string;
      };
      attributes?: Record<string, unknown>;
      startTime?: Date;
      endTime?: Date;
      duration?: number;
    }[];
    hasMore?: boolean;
    nextPageToken?: string;
    meta?: {
      requestId?: string;
      from?: Date;
      to?: Date;
      rowCount?: number;
    };
  };
}

Search Traces

Search trace summaries using the structured trace filter contract. See the filter grammar for the field and operator reference.

from orq_ai_sdk import Orq
from orq_ai_sdk.utils import parse_datetime
import os

with Orq(
    api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:

    res = orq.traces.search(from_=parse_datetime("2025-05-02T22:00:26.030Z"), to=parse_datetime("2025-09-17T16:33:38.335Z"))

    # Handle response
    print(res)

import { Orq } from "@orq-ai/node";

const orq = new Orq({
  apiKey: process.env["ORQ_API_KEY"] ?? "",
});

async function run() {
  const result = await orq.traces.search({
    from: new Date("2025-05-02T22:00:26.030Z"),
    to: new Date("2025-09-17T16:33:38.335Z"),
  });

  console.log(result);
}

run();

Show Parameters

{
    "from_": str,  # required
    "to": str,  # required
    "filters": [{  # optional
        "field": Optional[str],
        "op": Optional[str],
        "values": List[str],  # optional
    }],
    "filter_operator": Optional[str],
    "query": Optional[str],
    "sort": [{  # optional
        "field": Optional[str],
        "order": Optional[str],
    }],
    "limit": Optional[int],
    "page_token": Optional[str],
}

{
  from: Date;  // required
  to: Date;  // required
  filters?: {
    field?: string;
    op?: string;
    values?: string[];
  }[];
  filterOperator?: string;
  query?: string;
  sort?: {
    field?: string;
    order?: string;
  }[];
  limit?: number;
  pageToken?: string;
}

Show Response

{
    "object": Optional[Literal["list"]],
    "data": [{  # optional
        "object": Optional[Literal["trace"]],
        "trace_id": Optional[str],
        "root_span_id": Optional[str],
        "leading_span_id": Optional[str],
        "name": Optional[str],
        "operation": Optional[str],
        "status": Optional[str],
        "started_at": str,  # optional
        "ended_at": str,  # optional
        "duration_ms": Optional[float],
        "project_id": Optional[str],
        "identity_id": Optional[str],
        "session_id": Optional[str],
        "thread_id": Optional[str],
        "product": Optional[str],
        "providers": List[str],  # optional
        "models": List[str],  # optional
        "agent": {  # optional
            "id": Optional[str],
            "name": Optional[str],
        },
        "usage": {  # optional
            "prompt_tokens": Optional[int],
            "completion_tokens": Optional[int],
            "total_tokens": Optional[int],
            "prompt_cached_tokens": Optional[int],
            "prompt_audio_tokens": Optional[int],
            "completion_reasoning_tokens": Optional[int],
            "completion_audio_tokens": Optional[int],
            "completion_accepted_prediction_tokens": Optional[int],
            "completion_rejected_prediction_tokens": Optional[int],
            "prompt_cache_creation_tokens": Optional[int],
        },
        "cost": {  # optional
            "input": Optional[float],
            "output": Optional[float],
            "cache_read": Optional[float],
            "cache_write": Optional[float],
            "reasoning": Optional[float],
            "web_search": Optional[float],
            "total": Optional[float],
            "currency": Optional[str],
            "cached": Optional[float],
            "audio_input": Optional[float],
            "audio_output": Optional[float],
            "accepted_prediction": Optional[float],
            "rejected_prediction": Optional[float],
            "billable": Optional[bool],
            "pricing_tier": Optional[str],
            "threshold_exceeded": Optional[bool],
            "integration_id": Optional[str],
        },
        "id": Optional[str],
        "span_id": Optional[str],
        "parent_id": Optional[str],
        "type": Optional[str],
        "context": {  # optional
            "trace_id": Optional[str],
            "span_id": Optional[str],
        },
        "attributes": Dict[str, Any],  # optional
        "start_time": str,  # optional
        "end_time": str,  # optional
        "duration": Optional[float],
    }],
    "has_more": Optional[bool],
    "next_page_token": Optional[str],
    "meta": {  # optional
        "request_id": Optional[str],
        "from_": str,  # optional
        "to": str,  # optional
        "row_count": Optional[int],
    },
}

{
  object?: "list";
  data?: {
    object?: "trace";
    traceId?: string;
    rootSpanId?: string;
    leadingSpanId?: string;
    name?: string;
    operation?: string;
    status?: string;
    startedAt?: Date;
    endedAt?: Date;
    durationMs?: number;
    projectId?: string;
    identityId?: string;
    sessionId?: string;
    threadId?: string;
    product?: string;
    providers?: string[];
    models?: string[];
    agent?: {
      id?: string;
      name?: string;
    };
    usage?: {
      promptTokens?: number;
      completionTokens?: number;
      totalTokens?: number;
      promptCachedTokens?: number;
      promptAudioTokens?: number;
      completionReasoningTokens?: number;
      completionAudioTokens?: number;
      completionAcceptedPredictionTokens?: number;
      completionRejectedPredictionTokens?: number;
      promptCacheCreationTokens?: number;
    };
    cost?: {
      input?: number;
      output?: number;
      cacheRead?: number;
      cacheWrite?: number;
      reasoning?: number;
      webSearch?: number;
      total?: number;
      currency?: string;
      cached?: number;
      audioInput?: number;
      audioOutput?: number;
      acceptedPrediction?: number;
      rejectedPrediction?: number;
      billable?: boolean;
      pricingTier?: string;
      thresholdExceeded?: boolean;
      integrationId?: string;
    };
    id?: string;
    spanId?: string;
    parentId?: string;
    type?: string;
    context?: {
      traceId?: string;
      spanId?: string;
    };
    attributes?: Record<string, unknown>;
    startTime?: Date;
    endTime?: Date;
    duration?: number;
  }[];
  hasMore?: boolean;
  nextPageToken?: string;
  meta?: {
    requestId?: string;
    from?: Date;
    to?: Date;
    rowCount?: number;
  };
}

Retrieve a Trace

Retrieve one trace summary by trace id.

from orq_ai_sdk import Orq
import os

with Orq(
    api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:

    res = orq.traces.get(trace_id="<id>")

    # Handle response
    print(res)

import { Orq } from "@orq-ai/node";

const orq = new Orq({
  apiKey: process.env["ORQ_API_KEY"] ?? "",
});

async function run() {
  const result = await orq.traces.get({
    traceId: "<id>",
  });

  console.log(result);
}

run();

Show Parameters

{
    "trace_id": str,  # required
}

{
  traceId: string;  // required
}

Show Response

{
    "trace": {  # optional
        "object": Optional[Literal["trace"]],
        "trace_id": Optional[str],
        "root_span_id": Optional[str],
        "leading_span_id": Optional[str],
        "name": Optional[str],
        "operation": Optional[str],
        "status": Optional[str],
        "started_at": str,  # optional
        "ended_at": str,  # optional
        "duration_ms": Optional[float],
        "project_id": Optional[str],
        "identity_id": Optional[str],
        "session_id": Optional[str],
        "thread_id": Optional[str],
        "product": Optional[str],
        "providers": List[str],  # optional
        "models": List[str],  # optional
        "agent": {  # optional
            "id": Optional[str],
            "name": Optional[str],
        },
        "usage": {  # optional
            "prompt_tokens": Optional[int],
            "completion_tokens": Optional[int],
            "total_tokens": Optional[int],
            "prompt_cached_tokens": Optional[int],
            "prompt_audio_tokens": Optional[int],
            "completion_reasoning_tokens": Optional[int],
            "completion_audio_tokens": Optional[int],
            "completion_accepted_prediction_tokens": Optional[int],
            "completion_rejected_prediction_tokens": Optional[int],
            "prompt_cache_creation_tokens": Optional[int],
        },
        "cost": {  # optional
            "input": Optional[float],
            "output": Optional[float],
            "cache_read": Optional[float],
            "cache_write": Optional[float],
            "reasoning": Optional[float],
            "web_search": Optional[float],
            "total": Optional[float],
            "currency": Optional[str],
            "cached": Optional[float],
            "audio_input": Optional[float],
            "audio_output": Optional[float],
            "accepted_prediction": Optional[float],
            "rejected_prediction": Optional[float],
            "billable": Optional[bool],
            "pricing_tier": Optional[str],
            "threshold_exceeded": Optional[bool],
            "integration_id": Optional[str],
        },
        "id": Optional[str],
        "span_id": Optional[str],
        "parent_id": Optional[str],
        "type": Optional[str],
        "context": {  # optional
            "trace_id": Optional[str],
            "span_id": Optional[str],
        },
        "attributes": Dict[str, Any],  # optional
        "start_time": str,  # optional
        "end_time": str,  # optional
        "duration": Optional[float],
    },
}

{
  trace?: {
    object?: "trace";
    traceId?: string;
    rootSpanId?: string;
    leadingSpanId?: string;
    name?: string;
    operation?: string;
    status?: string;
    startedAt?: Date;
    endedAt?: Date;
    durationMs?: number;
    projectId?: string;
    identityId?: string;
    sessionId?: string;
    threadId?: string;
    product?: string;
    providers?: string[];
    models?: string[];
    agent?: {
      id?: string;
      name?: string;
    };
    usage?: {
      promptTokens?: number;
      completionTokens?: number;
      totalTokens?: number;
      promptCachedTokens?: number;
      promptAudioTokens?: number;
      completionReasoningTokens?: number;
      completionAudioTokens?: number;
      completionAcceptedPredictionTokens?: number;
      completionRejectedPredictionTokens?: number;
      promptCacheCreationTokens?: number;
    };
    cost?: {
      input?: number;
      output?: number;
      cacheRead?: number;
      cacheWrite?: number;
      reasoning?: number;
      webSearch?: number;
      total?: number;
      currency?: string;
      cached?: number;
      audioInput?: number;
      audioOutput?: number;
      acceptedPrediction?: number;
      rejectedPrediction?: number;
      billable?: boolean;
      pricingTier?: string;
      thresholdExceeded?: boolean;
      integrationId?: string;
    };
    id?: string;
    spanId?: string;
    parentId?: string;
    type?: string;
    context?: {
      traceId?: string;
      spanId?: string;
    };
    attributes?: Record<string, unknown>;
    startTime?: Date;
    endTime?: Date;
    duration?: number;
  };
}

Get Conversation

Return ordered OpenResponses items from the selected model-call span. Prefers spans with output outside evaluator subtrees unless span_id is given.

from orq_ai_sdk import Orq
import os

with Orq(
    api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:

    res = orq.traces.get_conversation(trace_id="<id>")

    # Handle response
    print(res)

import { Orq } from "@orq-ai/node";

const orq = new Orq({
  apiKey: process.env["ORQ_API_KEY"] ?? "",
});

async function run() {
  const result = await orq.traces.getConversation({
    traceId: "<id>",
  });

  console.log(result);
}

run();

Show Parameters

{
    "trace_id": str,  # required
    "span_id": Optional[str],
}

{
  traceId: string;  // required
  spanId?: string;
}

Show Response

{
    "trace_id": Optional[str],
    "span_id": Optional[str],
    "items": List[Dict[str, Any]],  # optional
}

{
  traceId?: string;
  spanId?: string;
  items?: Record<string, unknown>[];
}

List Spans

List canonical span summaries for a trace.

from orq_ai_sdk import Orq
import os

with Orq(
    api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:

    res = orq.traces.list_spans(trace_id="<id>")

    # Handle response
    print(res)

import { Orq } from "@orq-ai/node";

const orq = new Orq({
  apiKey: process.env["ORQ_API_KEY"] ?? "",
});

async function run() {
  const result = await orq.traces.listSpans({
    traceId: "<id>",
  });

  console.log(result);
}

run();

Show Parameters

{
    "trace_id": str,  # required
    "limit": Optional[int],
    "page_token": Optional[str],
}

{
  traceId: string;  // required
  limit?: number;
  pageToken?: string;
}

Show Response

{
    "object": Optional[str],
    "data": [{  # optional
        "object": Optional[str],
        "trace_id": Optional[str],
        "span_id": Optional[str],
        "parent_span_id": Optional[str],
        "name": Optional[str],
        "type": Optional[str],
        "operation": Optional[str],
        "status": Optional[str],
        "started_at": str,  # optional
        "ended_at": str,  # optional
        "duration_ms": Optional[float],
        "provider": Optional[str],
        "model": Optional[str],
        "usage": {  # optional
            "prompt_tokens": Optional[int],
            "completion_tokens": Optional[int],
            "total_tokens": Optional[int],
            "prompt_cached_tokens": Optional[int],
            "prompt_audio_tokens": Optional[int],
            "completion_reasoning_tokens": Optional[int],
            "completion_audio_tokens": Optional[int],
            "completion_accepted_prediction_tokens": Optional[int],
            "completion_rejected_prediction_tokens": Optional[int],
            "prompt_cache_creation_tokens": Optional[int],
        },
        "cost": {  # optional
            "input": Optional[float],
            "output": Optional[float],
            "cache_read": Optional[float],
            "cache_write": Optional[float],
            "reasoning": Optional[float],
            "web_search": Optional[float],
            "total": Optional[float],
            "currency": Optional[str],
            "cached": Optional[float],
            "audio_input": Optional[float],
            "audio_output": Optional[float],
            "accepted_prediction": Optional[float],
            "rejected_prediction": Optional[float],
            "billable": Optional[bool],
            "pricing_tier": Optional[str],
            "threshold_exceeded": Optional[bool],
            "integration_id": Optional[str],
        },
        "has_detail": Optional[bool],
        "level": Optional[int],
        "has_children": Optional[bool],
        "trace_framework": Optional[str],
        "leading_span_type": Optional[str],
        "guardrail_enabled": Optional[bool],
    }],
    "has_more": Optional[bool],
    "next_page_token": Optional[str],
}

{
  object?: string;
  data?: {
    object?: string;
    traceId?: string;
    spanId?: string;
    parentSpanId?: string;
    name?: string;
    type?: string;
    operation?: string;
    status?: string;
    startedAt?: Date;
    endedAt?: Date;
    durationMs?: number;
    provider?: string;
    model?: string;
    usage?: {
      promptTokens?: number;
      completionTokens?: number;
      totalTokens?: number;
      promptCachedTokens?: number;
      promptAudioTokens?: number;
      completionReasoningTokens?: number;
      completionAudioTokens?: number;
      completionAcceptedPredictionTokens?: number;
      completionRejectedPredictionTokens?: number;
      promptCacheCreationTokens?: number;
    };
    cost?: {
      input?: number;
      output?: number;
      cacheRead?: number;
      cacheWrite?: number;
      reasoning?: number;
      webSearch?: number;
      total?: number;
      currency?: string;
      cached?: number;
      audioInput?: number;
      audioOutput?: number;
      acceptedPrediction?: number;
      rejectedPrediction?: number;
      billable?: boolean;
      pricingTier?: string;
      thresholdExceeded?: boolean;
      integrationId?: string;
    };
    hasDetail?: boolean;
    level?: number;
    hasChildren?: boolean;
    traceFramework?: string;
    leadingSpanType?: string;
    guardrailEnabled?: boolean;
  }[];
  hasMore?: boolean;
  nextPageToken?: string;
}

Get Span

Retrieve one hydrated span.

from orq_ai_sdk import Orq
import os

with Orq(
    api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:

    res = orq.traces.get_span(trace_id="<id>", span_id="<id>")

    # Handle response
    print(res)

import { Orq } from "@orq-ai/node";

const orq = new Orq({
  apiKey: process.env["ORQ_API_KEY"] ?? "",
});

async function run() {
  const result = await orq.traces.getSpan({
    traceId: "<id>",
    spanId: "<id>",
  });

  console.log(result);
}

run();

Show Parameters

{
    "trace_id": str,  # required
    "span_id": str,  # required
}

{
  traceId: string;  // required
  spanId: string;  // required
}

Show Response

{
    "span": {  # optional
        "summary": {  # optional
            "object": Optional[str],
            "trace_id": Optional[str],
            "span_id": Optional[str],
            "parent_span_id": Optional[str],
            "name": Optional[str],
            "type": Optional[str],
            "operation": Optional[str],
            "status": Optional[str],
            "started_at": str,  # optional
            "ended_at": str,  # optional
            "duration_ms": Optional[float],
            "provider": Optional[str],
            "model": Optional[str],
            "usage": {  # optional
                "prompt_tokens": Optional[int],
                "completion_tokens": Optional[int],
                "total_tokens": Optional[int],
                "prompt_cached_tokens": Optional[int],
                "prompt_audio_tokens": Optional[int],
                "completion_reasoning_tokens": Optional[int],
                "completion_audio_tokens": Optional[int],
                "completion_accepted_prediction_tokens": Optional[int],
                "completion_rejected_prediction_tokens": Optional[int],
                "prompt_cache_creation_tokens": Optional[int],
            },
            "cost": {  # optional
                "input": Optional[float],
                "output": Optional[float],
                "cache_read": Optional[float],
                "cache_write": Optional[float],
                "reasoning": Optional[float],
                "web_search": Optional[float],
                "total": Optional[float],
                "currency": Optional[str],
                "cached": Optional[float],
                "audio_input": Optional[float],
                "audio_output": Optional[float],
                "accepted_prediction": Optional[float],
                "rejected_prediction": Optional[float],
                "billable": Optional[bool],
                "pricing_tier": Optional[str],
                "threshold_exceeded": Optional[bool],
                "integration_id": Optional[str],
            },
            "has_detail": Optional[bool],
            "level": Optional[int],
            "has_children": Optional[bool],
            "trace_framework": Optional[str],
            "leading_span_type": Optional[str],
            "guardrail_enabled": Optional[bool],
        },
        "attributes": Dict[str, Any],  # optional
    },
}

{
  span?: {
    summary?: {
      object?: string;
      traceId?: string;
      spanId?: string;
      parentSpanId?: string;
      name?: string;
      type?: string;
      operation?: string;
      status?: string;
      startedAt?: Date;
      endedAt?: Date;
      durationMs?: number;
      provider?: string;
      model?: string;
      usage?: {
        promptTokens?: number;
        completionTokens?: number;
        totalTokens?: number;
        promptCachedTokens?: number;
        promptAudioTokens?: number;
        completionReasoningTokens?: number;
        completionAudioTokens?: number;
        completionAcceptedPredictionTokens?: number;
        completionRejectedPredictionTokens?: number;
        promptCacheCreationTokens?: number;
      };
      cost?: {
        input?: number;
        output?: number;
        cacheRead?: number;
        cacheWrite?: number;
        reasoning?: number;
        webSearch?: number;
        total?: number;
        currency?: string;
        cached?: number;
        audioInput?: number;
        audioOutput?: number;
        acceptedPrediction?: number;
        rejectedPrediction?: number;
        billable?: boolean;
        pricingTier?: string;
        thresholdExceeded?: boolean;
        integrationId?: string;
      };
      hasDetail?: boolean;
      level?: number;
      hasChildren?: boolean;
      traceFramework?: string;
      leadingSpanType?: string;
      guardrailEnabled?: boolean;
    };
    attributes?: Record<string, unknown>;
  };
}

Orq SDK

Terminal & Agents

Terraform

Platform APIs

Management APIs

Traces

Aggregate Traces

List Facets

List Facet Values

List Fields

List Filters

Query Traces

Search Traces

Retrieve a Trace

Get Conversation

List Spans

Get Span

​Traces

​Aggregate Traces

​List Facets

​List Facet Values

​List Fields

​List Filters

​Query Traces

​Search Traces

​Retrieve a Trace

​Get Conversation

​List Spans

​Get Span

Traces

Aggregate Traces

List Facets

List Facet Values

List Fields

List Filters

Query Traces

Search Traces

Retrieve a Trace

Get Conversation

List Spans

Get Span