Skip to main content

Query Trace Data with the Agenta API

Google Colaboratory

Open in Google Colaboratory

The Agenta API lets you query trace and span data programmatically. You can filter by attributes, time ranges, and status codes. The API returns data in two formats: flat spans or hierarchical trace trees.

API Endpoint​

POST /api/preview/tracing/spans/query

Send queries as JSON in the request body. This approach works best for complex filters with nested conditions.

Authentication​

Include your API key in the request header:

Authorization: ApiKey YOUR_API_KEY

You can create API keys from the Settings page in your Agenta workspace.

Response Format Options​

Focus Parameter​

Choose how the API returns your data:

span: Returns individual spans in a flat list. Use this when you need span-level details.

{
  "focus": "span"
}

Example response:

{
  "count": 2,
  "spans": [
    {
      "trace_id": "abc123",
      "span_id": "span001",
      "parent_id": "root",
      "span_name": "openai.chat",
      "status_code": "STATUS_CODE_OK",
      "attributes": {
        "ag": {
          "metrics": {
            "costs": { "cumulative": { "total": 0.0023 } },
            "tokens": { "cumulative": { "total": 450 } }
          }
        }
      }
    },
    {
      "trace_id": "def456",
      "span_id": "span002",
      "parent_id": "root",
      "span_name": "generate_response",
      "status_code": "STATUS_CODE_OK",
      "attributes": { "..." }
    }
  ]
}

trace (default): Returns complete traces as hierarchical trees. Each trace groups its spans by trace_id. Use this when you need to see the full request flow.

{
  "focus": "trace"
}

Example response:

{
  "count": 1,
  "traces": {
    "abc123": {
      "spans": {
        "generate_response": {
          "span_id": "root",
          "span_name": "generate_response",
          "status_code": "STATUS_CODE_OK",
          "spans": {
            "openai.chat": {
              "span_id": "span001",
              "span_name": "openai.chat",
              "parent_id": "root",
              "status_code": "STATUS_CODE_OK",
              "attributes": {
                "ag": {
                  "metrics": {
                    "costs": { "cumulative": { "total": 0.0023 } },
                    "tokens": { "cumulative": { "total": 450 } }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

Time Windows and Limits​

Control which traces you retrieve using time ranges and result limits.

Time Range​

Specify start and end timestamps using ISO 8601 format or Unix timestamps:

{
  "oldest": "2024-01-01T00:00:00Z",
  "newest": "2024-01-31T23:59:59Z"
}

The oldest timestamp is included in results. The newest timestamp is excluded.

You can also use Unix timestamps (in seconds):

{
  "oldest": 1704067200,
  "newest": 1706745599
}

Result Limit​

Limit the number of results:

{
  "limit": 100
}

Combine time ranges with limits for precise control:

{
  "oldest": "2024-01-01T00:00:00Z",
  "newest": "2024-01-31T23:59:59Z",
  "limit": 50
}

Filtering Data​

Filter traces and spans using conditions with various operators.

Basic Filter Structure​

Each filter needs an operator and conditions:

{
  "filter": {
    "operator": "and",
    "conditions": [
      {
        "field": "span_name",
        "operator": "is",
        "value": "my_span"
      }
    ]
  }
}

Logical Operators​

Combine conditions using these operators:

and (default): All conditions must match.

or: At least one condition must match.

not: Negates the condition.

nand: At least one condition does not match.

nor: No conditions match.

Example using OR logic:

{
  "filter": {
    "operator": "or",
    "conditions": [
      { "field": "span_name", "value": "chat" },
      { "field": "span_name", "value": "completion" }
    ]
  }
}

Fields You Can Filter​

Filter by these standard fields:

trace_id: Trace identifier

span_id: Span identifier

parent_id: Parent span identifier

span_name: Span name

span_kind: Type of span (SPAN_KIND_UNSPECIFIED, SPAN_KIND_INTERNAL, SPAN_KIND_SERVER, SPAN_KIND_CLIENT, SPAN_KIND_PRODUCER, SPAN_KIND_CONSUMER)

start_time: Start timestamp

end_time: End timestamp

status_code: Status code (STATUS_CODE_UNSET, STATUS_CODE_OK, STATUS_CODE_ERROR)

status_message: Status message text

attributes: Span attributes (requires key parameter)

links: Linked spans

references: References to applications, variants, or revisions

Filtering by Attributes​

Access span attributes using the key parameter:

{
  "field": "attributes",
  "key": "ag.type.span",
  "operator": "is",
  "value": "llm"
}

For nested attributes, use dot notation:

{
  "field": "attributes",
  "key": "ag.metrics.unit.cost",
  "operator": "gt",
  "value": 0.01
}

Comparison Operators​

Equality​

is (default): Exact match

is_not: Not equal

{
  "field": "span_name",
  "operator": "is",
  "value": "openai.chat"
}

Numeric Comparisons​

eq: Equal to

neq: Not equal to

gt: Greater than

gte: Greater than or equal to

lt: Less than

lte: Less than or equal to

btwn: Between (inclusive, provide array [min, max])

Example filtering by duration:

{
  "field": "attributes",
  "key": "ag.metrics.unit.duration",
  "operator": "gt",
  "value": 1000
}

Example using between:

{
  "field": "attributes",
  "key": "ag.metrics.unit.duration",
  "operator": "btwn",
  "value": [500, 2000]
}

String Matching​

startswith: Starts with prefix

endswith: Ends with suffix

contains: Contains substring

matches: Regular expression match

like: SQL-like pattern (supports % wildcard)

Example searching span names:

{
  "field": "span_name",
  "operator": "contains",
  "value": "api"
}

List Operations​

in: Value exists in the list

not_in: Value does not exist in the list

Example filtering multiple traces:

{
  "field": "trace_id",
  "operator": "in",
  "value": [
    "trace_id_1",
    "trace_id_2",
    "trace_id_3"
  ]
}

Existence Checks​

exists: Field or attribute exists (any value, including null)

not_exists: Field or attribute does not exist

Example checking for cost tracking:

{
  "field": "attributes",
  "key": "ag.metrics.unit.cost",
  "operator": "exists"
}

Note: When using exists or not_exists, omit the value field.

Advanced Filtering Examples​

Multiple Conditions​

Filter production traces with slow response times:

{
  "filter": {
    "operator": "and",
    "conditions": [
      {
        "field": "attributes",
        "key": "environment",
        "value": "production"
      },
      {
        "field": "attributes",
        "key": "ag.metrics.unit.duration",
        "operator": "gt",
        "value": 1000
      },
      {
        "field": "status_code",
        "operator": "is_not",
        "value": "STATUS_CODE_ERROR"
      }
    ]
  }
}

Nested Logical Operators​

Find API calls that either errored or took too long:

{
  "filter": {
    "operator": "and",
    "conditions": [
      {
        "field": "span_name",
        "operator": "startswith",
        "value": "api_"
      },
      {
        "operator": "or",
        "conditions": [
          {
            "field": "status_code",
            "value": "STATUS_CODE_ERROR"
          },
          {
            "field": "attributes",
            "key": "ag.metrics.unit.duration",
            "operator": "gt",
            "value": 5000
          }
        ]
      }
    ]
  }
}

Filter by Application References​

Find traces for specific applications:

{
  "filter": {
    "conditions": [
      {
        "field": "references",
        "operator": "in",
        "value": [
          { "id": "application_id_1" },
          { "id": "application_id_2" }
        ]
      }
    ]
  }
}

Filter by Linked Spans​

Find spans linked to specific traces:

{
  "filter": {
    "conditions": [
      {
        "field": "links",
        "operator": "in",
        "value": [
          {
            "trace_id": "trace_id_value",
            "span_id": "span_id_value"
          }
        ]
      }
    ]
  }
}

Complete Query Example​

Here's a full query that finds successful LLM calls from the last month:

{
  "focus": "trace",
  "oldest": "2024-01-01T00:00:00Z",
  "newest": "2024-01-31T23:59:59Z",
  "limit": 50,
  "filter": {
    "operator": "and",
    "conditions": [
      {
        "field": "attributes",
        "key": "ag.type.span",
        "value": "llm"
      },
      {
        "field": "status_code",
        "operator": "is_not",
        "value": "STATUS_CODE_ERROR"
      }
    ]
  }
}

Response Structure​

The API returns JSON with these fields:

{
  "count": 42,
  "spans": [...],     // Present when focus=span
  "traces": {...}     // Present when focus=trace
}

count: Number of results returned

spans: Array of spans (when focus=span)

traces: Dictionary of trace trees indexed by trace_id (when focus=trace)

Span Format​

Each span contains:

{
  "trace_id": "...",
  "span_id": "...",
  "parent_id": "...",
  "span_name": "openai.chat",
  "span_kind": "SPAN_KIND_CLIENT",
  "start_time": "2024-01-15T10:30:00Z",
  "end_time": "2024-01-15T10:30:03Z",
  "status_code": "STATUS_CODE_OK",
  "attributes": {
    "ag": {
      "data": {
        "inputs": {...},
        "outputs": {...}
      },
      "metrics": {
        "costs": {...},
        "tokens": {...},
        "duration": {...}
      },
      "type": {
        "span": "llm"
      }
    }
  }
}

Trace Format​

Each trace organizes spans hierarchically by name:

{
  "trace_id_1": {
    "spans": {
      "root_span": {
        "span_id": "...",
        "spans": {
          "child_span": {
            "span_id": "...",
            "..."
          }
        }
      }
    }
  }
}

Error Responses​

The API returns standard HTTP status codes:

200 OK: Query succeeded

400 Bad Request: Invalid filter syntax or parameters

401 Unauthorized: Missing or invalid API key

422 Unprocessable Entity: Validation errors in the request

Python Example​

Here's a complete example using Python:

import requests
from datetime import datetime, timedelta, timezone

AGENTA_HOST = "https://cloud.agenta.ai"
API_KEY = "your_api_key_here"

# Query spans from the last 7 days
now = datetime.now(timezone.utc)
week_ago = now - timedelta(days=7)

query = {
    "focus": "span",
    "oldest": week_ago.isoformat(),
    "newest": now.isoformat(),
    "limit": 100,
    "filter": {
        "operator": "and",
        "conditions": [
            {
                "field": "attributes",
                "key": "ag.type.span",
                "value": "llm"
            },
            {
                "field": "status_code",
                "value": "STATUS_CODE_OK"
            }
        ]
    }
}

response = requests.post(
    f"{AGENTA_HOST}/api/preview/tracing/spans/query",
    headers={
        "Authorization": f"ApiKey {API_KEY}",
        "Content-Type": "application/json"
    },
    json=query
)

data = response.json()
print(f"Found {data['count']} spans")

JavaScript Example​

Here's the same query in JavaScript:

const AGENTA_HOST = "https://cloud.agenta.ai";
const API_KEY = "your_api_key_here";

// Query spans from the last 7 days
const now = new Date();
const weekAgo = new Date(now.getTime() - 7 * 24 * 60 * 60 * 1000);

const query = {
    focus: "span",
    oldest: weekAgo.toISOString(),
    newest: now.toISOString(),
    limit: 100,
    filter: {
        operator: "and",
        conditions: [
            {
                field: "attributes",
                key: "ag.type.span",
                value: "llm"
            },
            {
                field: "status_code",
                value: "STATUS_CODE_OK"
            }
        ]
    }
};

const response = await fetch(
    `${AGENTA_HOST}/api/preview/tracing/spans/query`,
    {
        method: "POST",
        headers: {
            "Authorization": `ApiKey ${API_KEY}`,
            "Content-Type": "application/json"
        },
        body: JSON.stringify(query)
    }
);

const data = await response.json();
console.log(`Found ${data.count} spans`);

Next Steps​

Learn about the Analytics Data API for aggregated metrics and time-series data.

Explore the API Reference for complete endpoint documentation.

Check out Filtering in the UI to learn about the visual query builder.