Interface GetObservationsRequest

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

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

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
• 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.

Scores (requires join with scores table)

• scores_avg (number) - Average of numeric scores (alias: scores)
• score_categories (categoryOptions) - Categorical score values

Associated Trace Fields (requires join with traces table)

• userId (string) - User ID from associated trace
• traceName (string) - Name from associated trace
• traceEnvironment (string) - Environment from associated trace
• traceTags (arrayOptions) - Tags from associated trace

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").

Limit of items per page. If you encounter api issues due to too large page sizes, try to reduce the limit.

Page number, starts at 1.

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

Optional filter to only include observations with a certain version.