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 field groups to include in the response. Available groups: core, basic, time, io, metadata, model, usage, prompt, metrics. 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"
                              // - 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"
                              // - 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

• metadata (stringObject/numberObject/categoryOptions) - Metadata key-value pairs. Use key parameter to filter on specific metadata keys.

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"
  }
]
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.

Set to true to parse input/output fields as JSON, or false to return raw strings. Defaults to false if not provided.

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.