Interface GetObservationsV2Request

Base64-encoded cursor for pagination. Use the cursor from the previous response to get the next page.

Optional filter for observations where the environment is one of the provided values.

Comma-separated list of metadata keys to return non-truncated. By default, metadata values over 200 characters are truncated. Use this parameter to retrieve full values for specific keys. Example: "key1,key2"

Comma-separated list of field groups to include in the response. Available groups: core, basic, time, io, metadata, model, usage, prompt, metrics, trace_context. If not specified, core and basic field groups are returned. Example: "basic,usage,model"

JSON string containing an array of filter conditions. When provided, this takes precedence over query parameter filters (userId, name, type, level, environment, fromStartTime, ...).

Filter Structure

Each filter condition has the following structure:

[
  {
    "type": string,           // Required. One of: "datetime", "string", "number", "stringOptions", "categoryOptions", "arrayOptions", "stringObject", "numberObject", "boolean", "null"
    "column": string,         // Required. Column to filter on (see available columns below)
    "operator": string,       // Required. Operator based on type:
                              // - datetime: ">", "<", ">=", "<="
                              // - string: "=", "contains", "does not contain", "starts with", "ends with", "matches"
                              // - stringOptions: "any of", "none of"
                              // - categoryOptions: "any of", "none of"
                              // - arrayOptions: "any of", "none of", "all of"
                              // - number: "=", ">", "<", ">=", "<="
                              // - stringObject: "=", "contains", "does not contain", "starts with", "ends with", "matches"
                              // - numberObject: "=", ">", "<", ">=", "<="
                              // - boolean: "=", "<>"
                              // - null: "is null", "is not null"
    "value": any,             // Required (except for null type). Value to compare against. Type depends on filter type
    "key": string             // Required only for stringObject, numberObject, and categoryOptions types when filtering on nested fields like metadata
  }
]
Copy

Available Columns

Core Observation Fields

• id (string) - Observation ID
• type (string) - Observation type (SPAN, GENERATION, EVENT)
• name (string) - Observation name
• traceId (string) - Associated trace ID
• startTime (datetime) - Observation start time
• endTime (datetime) - Observation end time
• environment (string) - Environment tag
• level (string) - Log level (DEBUG, DEFAULT, WARNING, ERROR)
• statusMessage (string) - Status message
• version (string) - Version tag
• userId (string) - User ID
• sessionId (string) - Session ID

Trace-Related Fields

• traceName (string) - Name of the parent trace
• traceTags (arrayOptions) - Tags from the parent trace
• tags (arrayOptions) - Alias for traceTags

Performance Metrics

• latency (number) - Latency in seconds (calculated: end_time - start_time)
• timeToFirstToken (number) - Time to first token in seconds
• tokensPerSecond (number) - Output tokens per second

Token Usage

• inputTokens (number) - Number of input tokens
• outputTokens (number) - Number of output tokens
• totalTokens (number) - Total tokens (alias: tokens)

Cost Metrics

• inputCost (number) - Input cost in USD
• outputCost (number) - Output cost in USD
• totalCost (number) - Total cost in USD

Model Information

• model (string) - Provided model name (alias: providedModelName)
• promptName (string) - Associated prompt name
• promptVersion (number) - Associated prompt version

Structured Data

• input (string) - Observation input. Supports accelerated indexed literal search with the matches operator.
• output (string) - Observation output. Supports accelerated indexed literal search with the matches operator.
• metadata (stringObject/numberObject/categoryOptions) - Metadata key-value pairs. Use key parameter to filter on specific metadata keys.

The matches operator is only supported for input, output, and stringObject metadata filters. It performs indexed literal search with token-boundary pruning using the events table text indexes. Case sensitivity differs by target: input and output matches are case-insensitive, while metadata value matches are case-sensitive. Unlike SQL LIKE, % and _ are treated as literal characters. Use contains for legacy substring semantics where the API allows it. Any v2 input or output filter must be accompanied by at least one = or matches filter on input or output; standalone contains, starts with, ends with, and does not contain filters on these columns are rejected.

Filter Examples

[
  {
    "type": "string",
    "column": "type",
    "operator": "=",
    "value": "GENERATION"
  },
  {
    "type": "number",
    "column": "latency",
    "operator": ">=",
    "value": 2.5
  },
  {
    "type": "stringObject",
    "column": "metadata",
    "key": "environment",
    "operator": "=",
    "value": "production"
  },
  {
    "type": "string",
    "column": "output",
    "operator": "matches",
    "value": "needle"
  }
]
Copy

Retrieve only observations with a start_time on or after this datetime (ISO 8601).

Optional filter for observations with a specific level (e.g. "DEBUG", "DEFAULT", "WARNING", "ERROR").

Number of items to return per page. Maximum 1000, default 50.

Deprecated. Setting this to true will return a 400 error. Input/output fields are always returned as raw strings. Remove this parameter or set it to false.

Retrieve only observations with a start_time before this datetime (ISO 8601).

Filter by observation type (e.g., "GENERATION", "SPAN", "EVENT", "AGENT", "TOOL", "CHAIN", "RETRIEVER", "EVALUATOR", "EMBEDDING", "GUARDRAIL")

Optional filter to only include observations with a certain version.