{ "opencollection": "1.0.0", "info": { "name": "langfuse AnnotationQueues Trace API", "version": "1.0" }, "items": [ { "info": { "name": "Trace", "type": "folder" }, "items": [ { "info": { "name": "trace_get", "type": "http" }, "http": { "method": "GET", "url": "{{baseUrl}}/api/public/traces/:traceId", "params": [ { "name": "traceId", "value": "", "type": "path", "description": "The unique langfuse identifier of a trace" }, { "name": "fields", "value": "", "type": "query", "description": "Comma-separated list of fields to include in the response. Available field groups: 'core' (always included), 'io' (input, output, metadata), 'scores', 'observations', 'metrics'. If not specified, all fields are returned. Example: 'core,scores,metrics'. Note: Excluded 'observations' or 'scores' fields return empty arrays; excluded 'metrics' returns -1 for 'totalCost' and 'latency'." } ], "auth": { "type": "basic", "username": "{{username}}", "password": "{{password}}" } }, "docs": "Get a specific trace" }, { "info": { "name": "trace_delete", "type": "http" }, "http": { "method": "DELETE", "url": "{{baseUrl}}/api/public/traces/:traceId", "params": [ { "name": "traceId", "value": "", "type": "path", "description": "The unique langfuse identifier of the trace to delete" } ], "auth": { "type": "basic", "username": "{{username}}", "password": "{{password}}" } }, "docs": "Delete a specific trace" }, { "info": { "name": "trace_list", "type": "http" }, "http": { "method": "GET", "url": "{{baseUrl}}/api/public/traces", "params": [ { "name": "page", "value": "", "type": "query", "description": "Page number, starts at 1" }, { "name": "limit", "value": "", "type": "query", "description": "Limit of items per page. If you encounter api issues due to too large page sizes, try to reduce the limit." }, { "name": "userId", "value": "", "type": "query" }, { "name": "name", "value": "", "type": "query" }, { "name": "sessionId", "value": "", "type": "query" }, { "name": "fromTimestamp", "value": "", "type": "query", "description": "Optional filter to only include traces with a trace.timestamp on or after a certain datetime (ISO 8601)" }, { "name": "toTimestamp", "value": "", "type": "query", "description": "Optional filter to only include traces with a trace.timestamp before a certain datetime (ISO 8601)" }, { "name": "orderBy", "value": "", "type": "query", "description": "Format of the string [field].[asc/desc]. Fields: id, timestamp, name, userId, release, version, public, bookmarked, sessionId. Example: timestamp.asc" }, { "name": "tags", "value": "", "type": "query", "description": "Only traces that include all of these tags will be returned." }, { "name": "version", "value": "", "type": "query", "description": "Optional filter to only include traces with a certain version." }, { "name": "release", "value": "", "type": "query", "description": "Optional filter to only include traces with a certain release." }, { "name": "environment", "value": "", "type": "query", "description": "Optional filter for traces where the environment is one of the provided values." }, { "name": "fields", "value": "", "type": "query", "description": "Comma-separated list of fields to include in the response. Available field groups: 'core' (always included), 'io' (input, output, metadata), 'scores', 'observations', 'metrics'. If not specified, all fields are returned. Example: 'core,scores,metrics'. Note: Excluded 'observations' or 'scores' fields return empty arrays; excluded 'metrics' returns -1 for 'totalCost' and 'latency'." }, { "name": "filter", "value": "", "type": "query", "description": "JSON string containing an array of filter conditions. When provided, this takes precedence over query parameter filters (userId, name, sessionId, tags, version, release, environment, fromTimestamp, toTimestamp).\n\n## Filter Structure\nEach filter condition has the following structure:\n```json\n[\n {\n \"type\": string, // Required. One of: \"datetime\", \"string\", \"number\", \"stringOptions\", \"categoryOptions\", \"arrayOptions\", \"stringObject\", \"numberObject\", \"boolean\", \"null\"\n \"column\": string, // Required. Column to filter on (see available columns below)\n \"operator\": string, // Required. Operator based on type:\n // - datetime: \">\", \"<\", \">=\", \"<=\"\n // - string: \"=\", \"contains\", \"does not contain\", \"starts with\", \"ends with\"\n // - stringOptions: \"any of\", \"none of\"\n // - categoryOptions: \"any of\", \"none of\"\n // - arrayOptions: \"any of\", \"none of\", \"all of\"\n // - number: \"=\", \">\", \"<\", \">=\", \"<=\"\n // - stringObject: \"=\", \"contains\", \"does not contain\", \"starts with\", \"ends with\"\n // - numberObject: \"=\", \">\", \"<\", \">=\", \"<=\"\n // - boolean: \"=\", \"<>\"\n // - null: \"is null\", \"is not null\"\n \"value\": any, // Required (except for null type). Value to compare against. Type depends on filter type\n \"key\": string // Required only for stringObject, numberObject, and categoryOptions types when filtering on nested fields like metadata\n }\n]\n```\n\n## Available Columns\n\n### Core Trace Fields\n- `id` (string) - Trace ID\n- `name` (string) - Trace name\n- `timestamp` (datetime) - Trace timestamp\n- `userId` (string) - User ID\n- `sessionId` (string) - Session ID\n- `environment` (string) - Environment tag\n- `version` (string) - Version tag\n- `release` (string) - Release tag\n- `tags` (arrayOptions) - Array of tags\n- `bookmarked` (boolean) - Bookmark status\n\n### Structured Data\n- `metadata` (stringObject/numberObject/categoryOptions) - Metadata key-value pairs. Use `key` parameter to filter on specific metadata keys.\n\n### Aggregated Metrics (from observations)\nThese metrics are aggregated from all observations within the trace:\n- `latency` (number) - Latency in seconds (time from first observation start to last observation end)\n- `inputTokens` (number) - Total input tokens across all observations\n- `outputTokens` (number) - Total output tokens across all observations\n- `totalTokens` (number) - Total tokens (alias: `tokens`)\n- `inputCost` (number) - Total input cost in USD\n- `outputCost` (number) - Total output cost in USD\n- `totalCost` (number) - Total cost in USD\n\n### Observation Level Aggregations\nThese fields aggregate observation levels within the trace:\n- `level` (string) - Highest severity level (ERROR > WARNING > DEFAULT > DEBUG)\n- `warningCount` (number) - Count of WARNING level observations\n- `errorCount` (number) - Count of ERROR level observations\n- `defaultCount` (number) - Count of DEFAULT level observations\n- `debugCount` (number) - Count of DEBUG level observations\n\n### Scores (requires join with scores table)\n- `scores_avg` (number) - Average of numeric scores (alias: `scores`)\n- `score_categories` (categoryOptions) - Categorical score values\n\n## Filter Examples\n```json\n[\n {\n \"type\": \"datetime\",\n \"column\": \"timestamp\",\n \"operator\": \">=\",\n \"value\": \"2024-01-01T00:00:00Z\"\n },\n {\n \"type\": \"string\",\n \"column\": \"userId\",\n \"operator\": \"=\",\n \"value\": \"user-123\"\n },\n {\n \"type\": \"number\",\n \"column\": \"totalCost\",\n \"operator\": \">=\",\n \"value\": 0.01\n },\n {\n \"type\": \"arrayOptions\",\n \"column\": \"tags\",\n \"operator\": \"all of\",\n \"value\": [\"production\", \"critical\"]\n },\n {\n \"type\": \"stringObject\",\n \"column\": \"metadata\",\n \"key\": \"customer_tier\",\n \"operator\": \"=\",\n \"value\": \"enterprise\"\n }\n]\n```\n\n## Performance Notes\n- Filtering on `userId`, `sessionId`, or `metadata` may enable skip indexes for better query performance\n- Score filters require a join with the scores table and may impact query performance" } ], "auth": { "type": "basic", "username": "{{username}}", "password": "{{password}}" } }, "docs": "Get list of traces" }, { "info": { "name": "trace_deleteMultiple", "type": "http" }, "http": { "method": "DELETE", "url": "{{baseUrl}}/api/public/traces", "body": { "type": "json", "data": "{}" }, "auth": { "type": "basic", "username": "{{username}}", "password": "{{password}}" } }, "docs": "Delete multiple traces" } ] } ], "bundled": true }