{ "openapi": "3.1.0", "info": { "title": "Latitude API", "version": "1.0.0", "description": "The Latitude public API. Authenticate using an API key via the `Authorization: Bearer` header." }, "servers": [ { "url": "https://api.latitude.so", "description": "Production" } ], "components": { "securitySchemes": { "ApiKeyAuth": { "type": "http", "scheme": "bearer", "description": "Organization-scoped API key" } }, "schemas": { "HealthResponse": { "type": "object", "properties": { "service": { "type": "string", "enum": [ "api" ] }, "status": { "type": "string", "enum": [ "ok" ] } }, "required": [ "service", "status" ] }, "OAuthProtectedResourceMetadata": { "type": "object", "properties": { "resource": { "type": "string" }, "authorization_servers": { "type": "array", "items": { "type": "string" } } }, "required": [ "resource", "authorization_servers" ] }, "Project": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable project identifier (CUID2)." }, "organizationId": { "type": "string", "description": "Organization that owns this project." }, "name": { "type": "string", "description": "Human-readable name." }, "slug": { "type": "string", "description": "URL-safe slug. Set from `name` at creation; renaming never changes it. It can only be changed from the dashboard, not via the API." }, "settings": { "$ref": "#/components/schemas/ProjectSettings" }, "firstTraceAt": { "type": [ "string", "null" ], "description": "ISO-8601 timestamp of the first ingested trace. `null` until the first trace lands." }, "deletedAt": { "type": [ "string", "null" ], "description": "ISO-8601 timestamp at which the project was deleted. `null` while the project is active." }, "lastEditedAt": { "type": "string", "description": "ISO-8601 timestamp of the most recent name/settings edit." }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp of creation." }, "updatedAt": { "type": "string", "description": "ISO-8601 timestamp of the last metadata change." } }, "required": [ "id", "organizationId", "name", "slug", "settings", "firstTraceAt", "deletedAt", "lastEditedAt", "createdAt", "updatedAt" ] }, "ProjectSettings": { "type": [ "object", "null" ], "properties": { "keepMonitoring": { "type": "boolean", "description": "When `true`, the evaluation linked to an signal keeps running after the signal is resolved. When `false`, resolving the signal stops the evaluation. Defaults to `true` when omitted." }, "notifications": { "$ref": "#/components/schemas/NotificationsSetting" }, "escalation": { "$ref": "#/components/schemas/EscalationSetting" } }, "description": "Per-project settings overrides. `null` means inherit from the organization." }, "NotificationsSetting": { "type": "object", "properties": { "incidents": { "$ref": "#/components/schemas/IncidentNotificationsSetting" }, "destinations": { "$ref": "#/components/schemas/DestinationNotificationsSetting" } }, "description": "Per-group project-level notification toggles (`incidents`, `destinations`)." }, "IncidentNotificationsSetting": { "type": "object", "properties": { "issue.new": { "type": "boolean", "description": "Send a notification when a new signal is discovered. Defaults to `true` when omitted." }, "issue.regressed": { "type": "boolean", "description": "Send a notification when a previously-resolved signal regresses. Defaults to `true` when omitted." }, "issue.escalating": { "type": "boolean", "description": "Send a notification when an active signal is escalating in volume or severity. Defaults to `true` when omitted." } }, "description": "Per-alert-kind opt-out for incident notifications." }, "DestinationNotificationsSetting": { "type": "object", "properties": { "quarantine": { "type": "boolean", "description": "Notify org members when a data destination is quarantined after repeated sync failures. Defaults to `true` when omitted." } }, "description": "Project-level opt-out for data-destination notifications." }, "EscalationSetting": { "type": "object", "properties": { "sensitivity": { "type": "integer", "minimum": 1, "maximum": 6, "description": "Sensitivity of the escalation detector, 1 (most sensitive, more incidents) to 6 (least sensitive, fewer incidents). Defaults to a balanced value when omitted." } }, "description": "Tuning parameters for the escalation detector. Affects detector behaviour regardless of whether notifications are enabled." }, "Error": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "CreateProjectBody": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Human-readable name for the project. Must be unique within the organization." } }, "required": [ "name" ] }, "PaginatedProjects": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Project" }, "description": "Page of items, in the requested sort order." }, "nextCursor": { "type": [ "string", "null" ], "description": "Opaque cursor for fetching the next page. `null` when there are no more pages. Pass it back in `cursor` to continue." }, "hasMore": { "type": "boolean", "description": "`true` when there is at least one more page after this one." } }, "required": [ "items", "nextCursor", "hasMore" ] }, "UpdateProjectBody": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "New human-readable name. Renaming never changes the slug." }, "settings": { "allOf": [ { "$ref": "#/components/schemas/ProjectSettings" }, { "description": "Replace the project's settings overrides. Omit to leave settings untouched. To clear overrides entirely, edit via the web UI." } ] }, "flaggers": { "type": "object", "properties": { "frustration": { "type": "boolean" }, "nsfw": { "type": "boolean" }, "refusal": { "type": "boolean" }, "laziness": { "type": "boolean" }, "jailbreaking": { "type": "boolean" }, "forgetting": { "type": "boolean" }, "trashing": { "type": "boolean" }, "tool-call-errors": { "type": "boolean" }, "output-schema-validation": { "type": "boolean" }, "empty-response": { "type": "boolean" } }, "description": "Enable or disable specific flaggers for the project. Keys are flagger slugs; values are the new `enabled` state. Omitted slugs are left untouched." } } }, "ScoreResponse": { "anyOf": [ { "$ref": "#/components/schemas/CustomScoreResponse" }, { "$ref": "#/components/schemas/EvaluationScoreResponse" } ] }, "CustomScoreResponse": { "type": "object", "properties": { "id": { "type": "string", "minLength": 24, "maxLength": 24, "description": "Stable score identifier." }, "organizationId": { "type": "string", "minLength": 24, "maxLength": 24, "description": "Organization that owns this score." }, "projectId": { "type": "string", "minLength": 24, "maxLength": 24, "description": "Project this score lives in." }, "sessionId": { "type": [ "string", "null" ], "maxLength": 128, "description": "Session id lifted from the trace, when set. `null` when the trace has no session." }, "traceId": { "type": [ "string", "null" ], "minLength": 32, "maxLength": 32, "description": "Identifier of the scored trace." }, "spanId": { "type": [ "string", "null" ], "minLength": 16, "maxLength": 16, "description": "Span the score pins to. Defaults to the trace's last LLM-completion span." }, "simulationId": { "type": [ "string", "null" ], "minLength": 24, "maxLength": 24, "description": "Simulation reference, if any." }, "signalId": { "type": [ "string", "null" ], "minLength": 24, "maxLength": 24, "description": "Signal this score contributes to, if any." }, "value": { "type": "number", "minimum": 0, "maximum": 1, "description": "Normalized score value in [0, 1]." }, "passed": { "type": "boolean", "description": "Whether the score marks the output as passing." }, "feedback": { "type": "string", "description": "Free-text feedback explaining the score." }, "error": { "type": [ "string", "null" ], "minLength": 1, "description": "Generation error text, when score generation itself errored. `null` for successful scores." }, "errored": { "type": "boolean", "description": "`true` when the score could not be generated successfully." }, "duration": { "type": "integer", "minimum": 0, "description": "Score generation duration in nanoseconds." }, "tokens": { "type": "integer", "minimum": 0, "description": "LLM tokens consumed generating the score." }, "cost": { "type": "integer", "minimum": 0, "description": "Score cost in microcents (1/1,000,000 of a USD)." }, "draftedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO-8601 timestamp while the score is awaiting human confirmation. `null` for published / system scores." }, "annotatorId": { "type": [ "string", "null" ], "minLength": 24, "maxLength": 24, "description": "User who authored the score, if any." }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp at which the score was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp of the last metadata update." }, "source": { "type": "string", "enum": [ "custom" ], "description": "Discriminator. `\"custom\"` denotes a user-supplied score." }, "sourceId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "User-supplied tag identifying the score's origin (echoed from the request)." }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Arbitrary user-supplied metadata persisted alongside the score." } }, "required": [ "id", "organizationId", "projectId", "sessionId", "traceId", "spanId", "simulationId", "signalId", "value", "passed", "feedback", "error", "errored", "duration", "tokens", "cost", "draftedAt", "annotatorId", "createdAt", "updatedAt", "source", "sourceId", "metadata" ] }, "EvaluationScoreResponse": { "type": "object", "properties": { "id": { "type": "string", "minLength": 24, "maxLength": 24, "description": "Stable score identifier." }, "organizationId": { "type": "string", "minLength": 24, "maxLength": 24, "description": "Organization that owns this score." }, "projectId": { "type": "string", "minLength": 24, "maxLength": 24, "description": "Project this score lives in." }, "sessionId": { "type": [ "string", "null" ], "maxLength": 128, "description": "Session id lifted from the trace, when set. `null` when the trace has no session." }, "traceId": { "type": [ "string", "null" ], "minLength": 32, "maxLength": 32, "description": "Identifier of the scored trace." }, "spanId": { "type": [ "string", "null" ], "minLength": 16, "maxLength": 16, "description": "Span the score pins to. Defaults to the trace's last LLM-completion span." }, "simulationId": { "type": [ "string", "null" ], "minLength": 24, "maxLength": 24, "description": "Simulation reference, if any." }, "signalId": { "type": [ "string", "null" ], "minLength": 24, "maxLength": 24, "description": "Signal this score contributes to, if any." }, "value": { "type": "number", "minimum": 0, "maximum": 1, "description": "Normalized score value in [0, 1]." }, "passed": { "type": "boolean", "description": "Whether the score marks the output as passing." }, "feedback": { "type": "string", "description": "Free-text feedback explaining the score." }, "error": { "type": [ "string", "null" ], "minLength": 1, "description": "Generation error text, when score generation itself errored. `null` for successful scores." }, "errored": { "type": "boolean", "description": "`true` when the score could not be generated successfully." }, "duration": { "type": "integer", "minimum": 0, "description": "Score generation duration in nanoseconds." }, "tokens": { "type": "integer", "minimum": 0, "description": "LLM tokens consumed generating the score." }, "cost": { "type": "integer", "minimum": 0, "description": "Score cost in microcents (1/1,000,000 of a USD)." }, "draftedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO-8601 timestamp while the score is awaiting human confirmation. `null` for published / system scores." }, "annotatorId": { "type": [ "string", "null" ], "minLength": 24, "maxLength": 24, "description": "User who authored the score, if any." }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp at which the score was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp of the last metadata update." }, "source": { "type": "string", "enum": [ "evaluation" ], "description": "Discriminator. `\"evaluation\"` denotes a platform-generated evaluation score." }, "sourceId": { "type": "string", "minLength": 24, "maxLength": 24, "description": "CUID of the evaluation that produced this score." }, "metadata": { "$ref": "#/components/schemas/EvaluationScoreMetadata" } }, "required": [ "id", "organizationId", "projectId", "sessionId", "traceId", "spanId", "simulationId", "signalId", "value", "passed", "feedback", "error", "errored", "duration", "tokens", "cost", "draftedAt", "annotatorId", "createdAt", "updatedAt", "source", "sourceId", "metadata" ] }, "EvaluationScoreMetadata": { "type": "object", "properties": { "evaluationHash": { "type": "string", "description": "Hash of the evaluation script that produced this score; lets the platform track which version generated it." } }, "required": [ "evaluationHash" ], "description": "Evaluation-specific metadata." }, "CreateScoreBody": { "anyOf": [ { "$ref": "#/components/schemas/CreateCustomScoreBody" }, { "$ref": "#/components/schemas/CreateEvaluationScoreBody" } ] }, "CreateCustomScoreBody": { "type": "object", "properties": { "simulationId": { "type": [ "string", "null" ], "minLength": 24, "maxLength": 24, "default": null, "description": "Simulation this score is tied to, if any. `null` (default) when not part of a simulation." }, "value": { "type": "number", "minimum": 0, "maximum": 1, "description": "Normalized score value in [0, 1]. Higher = better." }, "passed": { "type": "boolean", "description": "Whether the scored output passes the evaluator's bar." }, "feedback": { "type": "string", "description": "Free-text feedback explaining the score." }, "error": { "type": [ "string", "null" ], "minLength": 1, "default": null, "description": "Generation error text, when score generation itself failed. `null` (default) for successful scores." }, "duration": { "type": "integer", "minimum": 0, "default": 0, "description": "Score generation duration in nanoseconds. `0` for externally-computed scores." }, "tokens": { "type": "integer", "minimum": 0, "default": 0, "description": "LLM tokens consumed generating the score, if any. `0` for externally-computed scores." }, "cost": { "type": "integer", "minimum": 0, "default": 0, "description": "Score cost in microcents (1/1,000,000 of a USD). `0` for externally-computed scores." }, "trace": { "$ref": "#/components/schemas/TraceRef" }, "sourceId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "User-supplied tag identifying the score's origin (e.g. `\"prod-pipeline\"`, `\"qa-script-v2\"`)." }, "metadata": { "type": "object", "additionalProperties": {}, "default": {}, "description": "Arbitrary user-supplied metadata persisted alongside the score." }, "_evaluation": { "type": "boolean", "enum": [ false ], "default": false, "description": "Discriminator: omit (or `false`) for custom scores. Required `true` for evaluation scores." } }, "required": [ "value", "passed", "feedback", "trace", "sourceId" ] }, "TraceRef": { "oneOf": [ { "type": "object", "properties": { "by": { "type": "string", "enum": [ "id" ], "description": "Match a single trace by its identifier. Pair with `id`." }, "id": { "type": "string", "minLength": 32, "maxLength": 32, "description": "32-character trace identifier." } }, "required": [ "by", "id" ] }, { "type": "object", "properties": { "by": { "type": "string", "enum": [ "filters" ], "description": "Match a single trace by a filter set. Pair with `filters`; exactly one trace must match." }, "filters": { "$ref": "#/components/schemas/FilterSet" } }, "required": [ "by", "filters" ] } ], "description": "Target trace. Either an explicit id or a filter set matching exactly one trace." }, "FilterSet": { "type": "object", "additionalProperties": { "type": "array", "items": { "$ref": "#/components/schemas/FilterCondition" } }, "description": "Filter set keyed by field name. Each entry holds an array of conditions ANDed together for that field; field-level groups are also ANDed across the set." }, "FilterCondition": { "type": "object", "properties": { "op": { "type": "string", "enum": [ "eq", "neq", "gt", "gte", "lt", "lte", "in", "notIn", "contains", "notContains", "gtePercentile" ], "description": "Comparison operator applied to the field's value (e.g. `eq`, `neq`, `in`). The full operator list lives in the API reference." }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } } ], "description": "Right-hand value compared against the field. Arrays are required for `in` / `notIn`-style operators." } }, "required": [ "op", "value" ] }, "CreateEvaluationScoreBody": { "type": "object", "properties": { "simulationId": { "type": [ "string", "null" ], "minLength": 24, "maxLength": 24, "default": null, "description": "Simulation this score is tied to, if any. `null` (default) when not part of a simulation." }, "value": { "type": "number", "minimum": 0, "maximum": 1, "description": "Normalized score value in [0, 1]. Higher = better." }, "passed": { "type": "boolean", "description": "Whether the scored output passes the evaluator's bar." }, "feedback": { "type": "string", "description": "Free-text feedback explaining the score." }, "error": { "type": [ "string", "null" ], "minLength": 1, "default": null, "description": "Generation error text, when score generation itself failed. `null` (default) for successful scores." }, "duration": { "type": "integer", "minimum": 0, "default": 0, "description": "Score generation duration in nanoseconds. `0` for externally-computed scores." }, "tokens": { "type": "integer", "minimum": 0, "default": 0, "description": "LLM tokens consumed generating the score, if any. `0` for externally-computed scores." }, "cost": { "type": "integer", "minimum": 0, "default": 0, "description": "Score cost in microcents (1/1,000,000 of a USD). `0` for externally-computed scores." }, "trace": { "$ref": "#/components/schemas/TraceRef" }, "_evaluation": { "type": "boolean", "enum": [ true ], "description": "Discriminator: `true` flags the body as an evaluation score (internal); `false`/omit for custom." }, "sourceId": { "type": "string", "minLength": 24, "maxLength": 24, "description": "CUID of the evaluation that produced this score." }, "metadata": { "$ref": "#/components/schemas/EvaluationScoreMetadata" } }, "required": [ "value", "passed", "feedback", "trace", "_evaluation", "sourceId", "metadata" ], "description": "Internal, don't use" }, "Annotation": { "type": "object", "properties": { "id": { "type": "string", "minLength": 24, "maxLength": 24, "description": "Stable annotation identifier." }, "organizationId": { "type": "string", "minLength": 24, "maxLength": 24, "description": "Organization that owns this annotation." }, "projectId": { "type": "string", "minLength": 24, "maxLength": 24, "description": "Project this annotation lives in." }, "sessionId": { "type": [ "string", "null" ], "maxLength": 128, "description": "Session id lifted from the annotated trace. `null` when the trace has no session." }, "traceId": { "type": [ "string", "null" ], "minLength": 32, "maxLength": 32, "description": "Identifier of the annotated trace." }, "spanId": { "type": [ "string", "null" ], "minLength": 16, "maxLength": 16, "description": "Span the annotation pins to. Defaults to the trace's last LLM-completion span." }, "simulationId": { "type": [ "string", "null" ], "minLength": 24, "maxLength": 24, "description": "Simulation reference, if any." }, "signalId": { "type": [ "string", "null" ], "minLength": 24, "maxLength": 24, "description": "Signal this annotation contributes to, if any." }, "value": { "type": "number", "minimum": 0, "maximum": 1, "description": "Normalized score value in [0, 1]. Higher = better." }, "passed": { "type": "boolean", "description": "Whether the annotation marks the output as passing." }, "feedback": { "type": "string", "description": "Free-text feedback explaining the score." }, "error": { "type": [ "string", "null" ], "minLength": 1, "description": "Generation error text, when the annotation itself errored. `null` for successful annotations." }, "errored": { "type": "boolean", "description": "`true` when the annotation could not be generated successfully." }, "duration": { "type": "integer", "minimum": 0, "description": "Generation duration in nanoseconds. `0` for human annotations." }, "tokens": { "type": "integer", "minimum": 0, "description": "Total LLM tokens consumed generating the score. `0` for human annotations." }, "cost": { "type": "integer", "minimum": 0, "description": "Total LLM cost in microcents (1/1,000,000 USD). `0` for human annotations." }, "draftedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO-8601 timestamp at which the annotation was drafted. `null` for published annotations." }, "annotatorId": { "type": [ "string", "null" ], "minLength": 24, "maxLength": 24, "description": "User who authored the annotation. `null` when not attributed to a user." }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp at which the annotation was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp of the last metadata update." }, "source": { "type": "string", "enum": [ "annotation" ], "description": "Always `\"annotation\"` for this shape." }, "sourceId": { "anyOf": [ { "type": "string", "enum": [ "UI", "API", "SYSTEM" ] }, { "type": "string", "minLength": 24, "maxLength": 24 } ], "description": "Origin marker. Sentinel `\"UI\"` / `\"API\"` / `\"SYSTEM\"` for drafts and automation, or an annotation-queue CUID for queue-authored rows." }, "metadata": { "$ref": "#/components/schemas/AnnotationMetadata" } }, "required": [ "id", "organizationId", "projectId", "sessionId", "traceId", "spanId", "simulationId", "signalId", "value", "passed", "feedback", "error", "errored", "duration", "tokens", "cost", "draftedAt", "annotatorId", "createdAt", "updatedAt", "source", "sourceId", "metadata" ] }, "AnnotationMetadata": { "type": "object", "properties": { "rawFeedback": { "type": "string", "description": "Original feedback text as written by the annotator, before any server-side enrichment." }, "messageIndex": { "type": "integer", "minimum": 0, "description": "0-based message index inside the conversation. Omit for conversation-level annotations." }, "partIndex": { "type": "integer", "minimum": 0, "description": "0-based index into the target message's `parts[]`. Requires `messageIndex`." }, "startOffset": { "type": "integer", "minimum": 0, "description": "Inclusive start offset for substring annotations. Must be paired with `endOffset` and `partIndex`." }, "endOffset": { "type": "integer", "minimum": 0, "description": "Exclusive end offset for substring annotations. Must be paired with `startOffset` and `partIndex`, and `>= startOffset`." }, "textFormat": { "type": "string", "enum": [ "pretty-json" ], "description": "UI-side text transform applied before the offsets were captured (e.g. `\"pretty-json\"`). Resolvers must apply the same transform before slicing." } }, "required": [ "rawFeedback" ], "description": "Annotation-specific metadata: `rawFeedback` plus a snapshot of the anchor at write time." }, "CreateAnnotationBody": { "type": "object", "properties": { "simulationId": { "type": [ "string", "null" ], "minLength": 24, "maxLength": 24, "default": null, "description": "Simulation this annotation is tied to, if any. `null` (default) when not part of a simulation." }, "signalId": { "type": [ "string", "null" ], "minLength": 24, "maxLength": 24, "default": null, "description": "Pre-selected signal this annotation belongs to. Leave `null` (default) to let the automatic signal-discovery pipeline route the annotation." }, "value": { "type": "number", "minimum": 0, "maximum": 1, "description": "Normalized score value in [0, 1]. Higher = better." }, "passed": { "type": "boolean", "description": "Whether the annotated output passes the reviewer's bar." }, "feedback": { "type": "string", "minLength": 1, "description": "Free-text feedback explaining the score. Surfaced alongside the trace." }, "anchor": { "$ref": "#/components/schemas/AnnotationAnchor" }, "trace": { "$ref": "#/components/schemas/TraceRef" } }, "required": [ "value", "passed", "feedback", "trace" ] }, "AnnotationAnchor": { "type": "object", "properties": { "messageIndex": { "type": "integer", "minimum": 0, "description": "0-based message index inside the conversation. Omit for conversation-level annotations." }, "partIndex": { "type": "integer", "minimum": 0, "description": "0-based index into the target message's `parts[]`. Requires `messageIndex`." }, "startOffset": { "type": "integer", "minimum": 0, "description": "Inclusive start offset for substring annotations. Must be paired with `endOffset` and `partIndex`." }, "endOffset": { "type": "integer", "minimum": 0, "description": "Exclusive end offset for substring annotations. Must be paired with `startOffset` and `partIndex`, and `>= startOffset`." }, "textFormat": { "type": "string", "enum": [ "pretty-json" ], "description": "UI-side text transform applied before the offsets were captured (e.g. `\"pretty-json\"`). Resolvers must apply the same transform before slicing." } }, "description": "Optional anchor pinning the annotation to a specific message / part / offset range inside the trace." }, "PaginatedTraces": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Trace" }, "description": "Page of items, in the requested sort order." }, "nextCursor": { "type": [ "string", "null" ], "description": "Opaque cursor for fetching the next page. `null` when there are no more pages. Pass it back in `cursor` to continue." }, "hasMore": { "type": "boolean", "description": "`true` when there is at least one more page after this one." } }, "required": [ "items", "nextCursor", "hasMore" ] }, "Trace": { "type": "object", "properties": { "organizationId": { "type": "string", "description": "Organization that owns this trace." }, "projectId": { "type": "string", "description": "Project this trace belongs to." }, "traceId": { "type": "string", "description": "32-character trace identifier." }, "spanCount": { "type": "integer", "minimum": 0, "description": "Total number of spans in the trace." }, "errorCount": { "type": "integer", "minimum": 0, "description": "Number of spans flagged with an error status." }, "startTime": { "type": "string", "description": "ISO-8601 timestamp of the trace's earliest span." }, "endTime": { "type": "string", "description": "ISO-8601 timestamp of the trace's latest span." }, "durationNs": { "type": "number", "description": "Wall-clock duration of the trace in nanoseconds." }, "timeToFirstTokenNs": { "type": "number", "description": "Nanoseconds from the start of the first LLM span to its first emitted token. `0` if not measured." }, "tokensInput": { "type": "number", "description": "Total input tokens across LLM spans." }, "tokensOutput": { "type": "number", "description": "Total output tokens across LLM spans." }, "tokensCacheRead": { "type": "number", "description": "Total tokens served from the provider's prompt cache." }, "tokensCacheCreate": { "type": "number", "description": "Total tokens written to the provider's prompt cache." }, "tokensReasoning": { "type": "number", "description": "Total reasoning tokens reported by the model." }, "tokensTotal": { "type": "number", "description": "Sum of all token counters." }, "costInputMicrocents": { "type": "number", "description": "Cost of input tokens in microcents (1/1,000,000 USD)." }, "costOutputMicrocents": { "type": "number", "description": "Cost of output tokens in microcents (1/1,000,000 USD)." }, "costTotalMicrocents": { "type": "number", "description": "Total cost in microcents (1/1,000,000 USD)." }, "sessionId": { "type": [ "string", "null" ], "description": "Conversation/session identifier set by the SDK. `null` when absent." }, "userId": { "type": [ "string", "null" ], "description": "End-user identifier set by the SDK. `null` when absent." }, "simulationId": { "type": [ "string", "null" ], "description": "CUID of the simulation that produced this trace. `null` when not a simulation." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Free-form tags attached at ingest time." }, "models": { "type": "array", "items": { "type": "string" }, "description": "Model identifiers seen across the trace's LLM spans." }, "providers": { "type": "array", "items": { "type": "string" }, "description": "LLM-provider identifiers seen across the trace's spans." }, "serviceNames": { "type": "array", "items": { "type": "string" }, "description": "OpenTelemetry `service.name` values seen in the trace." }, "rootSpanId": { "type": [ "string", "null" ], "description": "Identifier of the trace's root span. `null` when no root span has been ingested." }, "rootSpanName": { "type": [ "string", "null" ], "description": "`name` attribute of the root span. `null` when no root span has been ingested." }, "positiveAnnotationCount": { "type": "integer", "minimum": 0, "description": "Number of `passed = true` annotations attached to this trace." }, "negativeAnnotationCount": { "type": "integer", "minimum": 0, "description": "Number of `passed = false` annotations attached to this trace." } }, "required": [ "organizationId", "projectId", "traceId", "spanCount", "errorCount", "startTime", "endTime", "durationNs", "timeToFirstTokenNs", "tokensInput", "tokensOutput", "tokensCacheRead", "tokensCacheCreate", "tokensReasoning", "tokensTotal", "costInputMicrocents", "costOutputMicrocents", "costTotalMicrocents", "sessionId", "userId", "simulationId", "tags", "models", "providers", "serviceNames", "rootSpanId", "rootSpanName", "positiveAnnotationCount", "negativeAnnotationCount" ] }, "ListTracesBody": { "type": "object", "properties": { "cursor": { "type": "string", "description": "Opaque cursor returned in a previous response's `nextCursor`. Omit on the first page." }, "limit": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50, "description": "Page size. Defaults to 50; max 200." }, "sortBy": { "type": "string", "enum": [ "relevance", "startTime", "endTime", "durationNs", "tokensTotal", "costTotalMicrocents" ], "default": "startTime", "description": "Field to sort by. Defaults to `startTime`. Pass `relevance` together with `query` to rank by semantic match (best match first, then most recent)." }, "sortDirection": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc", "description": "Sort direction. Defaults to `desc` (most recent first)." }, "query": { "type": "string", "maxLength": 500, "description": "Free-text semantic search across the trace's input and output messages. Combined with `filters` via AND." }, "filters": { "$ref": "#/components/schemas/FilterSet" } } }, "TraceAnalyticsResponse": { "type": "object", "properties": { "traces": { "$ref": "#/components/schemas/TraceAnalyticsTraces" }, "cost": { "$ref": "#/components/schemas/TraceAnalyticsCost" }, "duration": { "$ref": "#/components/schemas/TraceAnalyticsDuration" }, "tokens": { "$ref": "#/components/schemas/TraceAnalyticsTokens" }, "timeToFirstToken": { "$ref": "#/components/schemas/TraceAnalyticsTimeToFirstToken" }, "spans": { "$ref": "#/components/schemas/TraceAnalyticsSpans" } }, "required": [ "traces", "cost", "duration", "tokens", "timeToFirstToken", "spans" ] }, "TraceAnalyticsTraces": { "type": "object", "properties": { "total": { "type": "number", "description": "Number of traces in the range." }, "buckets": { "type": "array", "items": { "$ref": "#/components/schemas/TraceAnalyticsBucket" }, "description": "Number of traces per bucket." } }, "required": [ "total", "buckets" ] }, "TraceAnalyticsBucket": { "type": "object", "properties": { "bucket": { "type": "string", "description": "ISO-8601 UTC timestamp of the bucket's start." }, "value": { "type": "number", "description": "Metric value for this bucket." } }, "required": [ "bucket", "value" ] }, "TraceAnalyticsCost": { "type": "object", "properties": { "total": { "type": "number", "description": "Total trace cost in USD." }, "buckets": { "type": "array", "items": { "$ref": "#/components/schemas/TraceAnalyticsBucket" }, "description": "Trace cost per bucket in USD." } }, "required": [ "total", "buckets" ] }, "TraceAnalyticsDuration": { "type": "object", "properties": { "median": { "type": "number", "description": "Median trace duration in seconds." }, "buckets": { "type": "array", "items": { "$ref": "#/components/schemas/TraceAnalyticsBucket" }, "description": "Median trace duration per bucket in seconds." } }, "required": [ "median", "buckets" ] }, "TraceAnalyticsTokens": { "type": "object", "properties": { "total": { "type": "number", "description": "Total tokens across all LLM spans." }, "buckets": { "type": "array", "items": { "$ref": "#/components/schemas/TraceAnalyticsBucket" }, "description": "Tokens per bucket across all LLM spans." } }, "required": [ "total", "buckets" ] }, "TraceAnalyticsTimeToFirstToken": { "type": "object", "properties": { "median": { "type": "number", "description": "Median time-to-first-token across LLM spans, in seconds." }, "buckets": { "type": "array", "items": { "$ref": "#/components/schemas/TraceAnalyticsBucket" }, "description": "Median time-to-first-token per bucket, in seconds." } }, "required": [ "median", "buckets" ] }, "TraceAnalyticsSpans": { "type": "object", "properties": { "total": { "type": "number", "description": "Total number of spans." }, "buckets": { "type": "array", "items": { "$ref": "#/components/schemas/TraceAnalyticsBucket" }, "description": "Number of spans per bucket." } }, "required": [ "total", "buckets" ] }, "TraceDetail": { "type": "object", "properties": { "organizationId": { "type": "string", "description": "Organization that owns this trace." }, "projectId": { "type": "string", "description": "Project this trace belongs to." }, "traceId": { "type": "string", "description": "32-character trace identifier." }, "spanCount": { "type": "integer", "minimum": 0, "description": "Total number of spans in the trace." }, "errorCount": { "type": "integer", "minimum": 0, "description": "Number of spans flagged with an error status." }, "startTime": { "type": "string", "description": "ISO-8601 timestamp of the trace's earliest span." }, "endTime": { "type": "string", "description": "ISO-8601 timestamp of the trace's latest span." }, "durationNs": { "type": "number", "description": "Wall-clock duration of the trace in nanoseconds." }, "timeToFirstTokenNs": { "type": "number", "description": "Nanoseconds from the start of the first LLM span to its first emitted token. `0` if not measured." }, "tokensInput": { "type": "number", "description": "Total input tokens across LLM spans." }, "tokensOutput": { "type": "number", "description": "Total output tokens across LLM spans." }, "tokensCacheRead": { "type": "number", "description": "Total tokens served from the provider's prompt cache." }, "tokensCacheCreate": { "type": "number", "description": "Total tokens written to the provider's prompt cache." }, "tokensReasoning": { "type": "number", "description": "Total reasoning tokens reported by the model." }, "tokensTotal": { "type": "number", "description": "Sum of all token counters." }, "costInputMicrocents": { "type": "number", "description": "Cost of input tokens in microcents (1/1,000,000 USD)." }, "costOutputMicrocents": { "type": "number", "description": "Cost of output tokens in microcents (1/1,000,000 USD)." }, "costTotalMicrocents": { "type": "number", "description": "Total cost in microcents (1/1,000,000 USD)." }, "sessionId": { "type": [ "string", "null" ], "description": "Conversation/session identifier set by the SDK. `null` when absent." }, "userId": { "type": [ "string", "null" ], "description": "End-user identifier set by the SDK. `null` when absent." }, "simulationId": { "type": [ "string", "null" ], "description": "CUID of the simulation that produced this trace. `null` when not a simulation." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Free-form tags attached at ingest time." }, "models": { "type": "array", "items": { "type": "string" }, "description": "Model identifiers seen across the trace's LLM spans." }, "providers": { "type": "array", "items": { "type": "string" }, "description": "LLM-provider identifiers seen across the trace's spans." }, "serviceNames": { "type": "array", "items": { "type": "string" }, "description": "OpenTelemetry `service.name` values seen in the trace." }, "rootSpanId": { "type": [ "string", "null" ], "description": "Identifier of the trace's root span. `null` when no root span has been ingested." }, "rootSpanName": { "type": [ "string", "null" ], "description": "`name` attribute of the root span. `null` when no root span has been ingested." }, "positiveAnnotationCount": { "type": "integer", "minimum": 0, "description": "Number of `passed = true` annotations attached to this trace." }, "negativeAnnotationCount": { "type": "integer", "minimum": 0, "description": "Number of `passed = false` annotations attached to this trace." }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Free-form metadata attached at ingest time." }, "systemInstructions": { "$ref": "#/components/schemas/GenAISystem" }, "inputMessages": { "type": "array", "items": { "$ref": "#/components/schemas/GenAIMessage" }, "description": "Input messages sent into the first LLM span of the trace, in OpenTelemetry GenAI format." }, "outputMessages": { "type": "array", "items": { "$ref": "#/components/schemas/GenAIMessage" }, "description": "Output messages from the last LLM span of the trace, in OpenTelemetry GenAI format." }, "allMessages": { "type": "array", "items": { "$ref": "#/components/schemas/GenAIMessage" }, "description": "Full conversation view for the trace's final turn — the last span's input messages followed by its output messages, in OpenTelemetry GenAI format." } }, "required": [ "organizationId", "projectId", "traceId", "spanCount", "errorCount", "startTime", "endTime", "durationNs", "timeToFirstTokenNs", "tokensInput", "tokensOutput", "tokensCacheRead", "tokensCacheCreate", "tokensReasoning", "tokensTotal", "costInputMicrocents", "costOutputMicrocents", "costTotalMicrocents", "sessionId", "userId", "simulationId", "tags", "models", "providers", "serviceNames", "rootSpanId", "rootSpanName", "positiveAnnotationCount", "negativeAnnotationCount", "metadata", "systemInstructions", "inputMessages", "outputMessages", "allMessages" ] }, "GenAISystem": { "type": "array", "items": { "type": "object", "additionalProperties": {} }, "description": "System instructions in OpenTelemetry GenAI format — an array of part objects." }, "GenAIMessage": { "type": "object", "additionalProperties": {}, "description": "Message in OpenTelemetry GenAI format (`role` + content parts + optional tool calls)." }, "TraceSpans": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Span" }, "description": "All spans belonging to the trace, ordered by `startTime` ascending." } }, "required": [ "items" ] }, "Span": { "type": "object", "properties": { "organizationId": { "type": "string", "description": "Organization that owns this span." }, "projectId": { "type": "string", "description": "Project this span belongs to." }, "traceId": { "type": "string", "description": "Identifier of the trace this span belongs to." }, "spanId": { "type": "string", "description": "Stable span identifier within the trace." }, "parentSpanId": { "type": [ "string", "null" ], "description": "Identifier of the parent span. `null` for root spans." }, "sessionId": { "type": [ "string", "null" ], "description": "Conversation/session identifier set by the SDK. `null` when absent." }, "userId": { "type": [ "string", "null" ], "description": "End-user identifier set by the SDK. `null` when absent." }, "simulationId": { "type": [ "string", "null" ], "description": "CUID of the simulation that produced this span. `null` when not a simulation." }, "apiKeyId": { "type": [ "string", "null" ], "description": "Latitude API key used to ingest the span. `null` when ingested without an API key." }, "startTime": { "type": "string", "description": "ISO-8601 timestamp at which the span started." }, "endTime": { "type": "string", "description": "ISO-8601 timestamp at which the span ended." }, "name": { "type": "string", "description": "Span name (e.g. the entry-point function or route)." }, "serviceName": { "type": "string", "description": "OpenTelemetry `service.name` of the emitting service." }, "kind": { "type": "string", "enum": [ "unspecified", "internal", "server", "client", "producer", "consumer" ], "description": "OpenTelemetry span kind." }, "statusCode": { "type": "string", "enum": [ "unset", "ok", "error" ], "description": "OpenTelemetry span status code." }, "statusMessage": { "type": "string", "description": "OpenTelemetry status message. Empty when not set." }, "traceFlags": { "type": "number", "description": "OpenTelemetry trace flags bitfield." }, "traceState": { "type": "string", "description": "OpenTelemetry trace state (vendor-specific propagation). Empty when not set." }, "errorType": { "type": [ "string", "null" ], "description": "Error class/type label when the span errored. `null` for successful spans." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Free-form tags attached at ingest time." }, "operation": { "type": "string", "description": "GenAI operation category (e.g. `\"chat\"`, `\"embeddings\"`, `\"execute_tool\"`, `\"invoke_agent\"`) or a custom string for non-GenAI spans." }, "provider": { "type": [ "string", "null" ], "description": "LLM provider id. `null` for non-LLM spans." }, "model": { "type": [ "string", "null" ], "description": "Model id as requested. `null` for non-LLM spans." }, "responseModel": { "type": [ "string", "null" ], "description": "Model id reported by the provider's response. `null` for non-LLM spans." }, "tokensInput": { "type": "number", "description": "Input tokens consumed by this span." }, "tokensOutput": { "type": "number", "description": "Output tokens produced by this span." }, "tokensCacheRead": { "type": "number", "description": "Tokens served from the provider's prompt cache." }, "tokensCacheCreate": { "type": "number", "description": "Tokens written to the provider's prompt cache." }, "tokensReasoning": { "type": "number", "description": "Reasoning tokens reported by the model." }, "costInputMicrocents": { "type": "number", "description": "Cost of input tokens in microcents (1/1,000,000 USD)." }, "costOutputMicrocents": { "type": "number", "description": "Cost of output tokens in microcents (1/1,000,000 USD)." }, "costTotalMicrocents": { "type": "number", "description": "Total cost in microcents (1/1,000,000 USD)." }, "costIsEstimated": { "type": "boolean", "description": "`true` when the cost was derived from public pricing tables instead of the provider's bill." }, "timeToFirstTokenNs": { "type": "number", "description": "Nanoseconds from the start of the span to its first emitted token. `0` if not measured." }, "isStreaming": { "type": "boolean", "description": "`true` when the span was produced by a streaming LLM call." }, "responseId": { "type": [ "string", "null" ], "description": "Response identifier returned by the LLM. `null` when the provider didn't return one." }, "finishReasons": { "type": "array", "items": { "type": "string" }, "description": "Per-choice finish reasons reported by the LLM provider." }, "scopeName": { "type": "string", "description": "OpenTelemetry instrumentation scope name. Empty when not set." }, "scopeVersion": { "type": "string", "description": "OpenTelemetry instrumentation scope version. Empty when not set." }, "retentionDays": { "type": "integer", "exclusiveMinimum": 0, "description": "Per-span retention override in days. Omitted when the project default applies." }, "ingestedAt": { "type": "string", "description": "ISO-8601 timestamp at which Latitude received this span." } }, "required": [ "organizationId", "projectId", "traceId", "spanId", "parentSpanId", "sessionId", "userId", "simulationId", "apiKeyId", "startTime", "endTime", "name", "serviceName", "kind", "statusCode", "statusMessage", "traceFlags", "traceState", "errorType", "tags", "operation", "provider", "model", "responseModel", "tokensInput", "tokensOutput", "tokensCacheRead", "tokensCacheCreate", "tokensReasoning", "costInputMicrocents", "costOutputMicrocents", "costTotalMicrocents", "costIsEstimated", "timeToFirstTokenNs", "isStreaming", "responseId", "finishReasons", "scopeName", "scopeVersion", "ingestedAt" ] }, "SpanDetail": { "type": "object", "properties": { "organizationId": { "type": "string", "description": "Organization that owns this span." }, "projectId": { "type": "string", "description": "Project this span belongs to." }, "traceId": { "type": "string", "description": "Identifier of the trace this span belongs to." }, "spanId": { "type": "string", "description": "Stable span identifier within the trace." }, "parentSpanId": { "type": [ "string", "null" ], "description": "Identifier of the parent span. `null` for root spans." }, "sessionId": { "type": [ "string", "null" ], "description": "Conversation/session identifier set by the SDK. `null` when absent." }, "userId": { "type": [ "string", "null" ], "description": "End-user identifier set by the SDK. `null` when absent." }, "simulationId": { "type": [ "string", "null" ], "description": "CUID of the simulation that produced this span. `null` when not a simulation." }, "apiKeyId": { "type": [ "string", "null" ], "description": "Latitude API key used to ingest the span. `null` when ingested without an API key." }, "startTime": { "type": "string", "description": "ISO-8601 timestamp at which the span started." }, "endTime": { "type": "string", "description": "ISO-8601 timestamp at which the span ended." }, "name": { "type": "string", "description": "Span name (e.g. the entry-point function or route)." }, "serviceName": { "type": "string", "description": "OpenTelemetry `service.name` of the emitting service." }, "kind": { "type": "string", "enum": [ "unspecified", "internal", "server", "client", "producer", "consumer" ], "description": "OpenTelemetry span kind." }, "statusCode": { "type": "string", "enum": [ "unset", "ok", "error" ], "description": "OpenTelemetry span status code." }, "statusMessage": { "type": "string", "description": "OpenTelemetry status message. Empty when not set." }, "traceFlags": { "type": "number", "description": "OpenTelemetry trace flags bitfield." }, "traceState": { "type": "string", "description": "OpenTelemetry trace state (vendor-specific propagation). Empty when not set." }, "errorType": { "type": [ "string", "null" ], "description": "Error class/type label when the span errored. `null` for successful spans." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Free-form tags attached at ingest time." }, "operation": { "type": "string", "description": "GenAI operation category (e.g. `\"chat\"`, `\"embeddings\"`, `\"execute_tool\"`, `\"invoke_agent\"`) or a custom string for non-GenAI spans." }, "provider": { "type": [ "string", "null" ], "description": "LLM provider id. `null` for non-LLM spans." }, "model": { "type": [ "string", "null" ], "description": "Model id as requested. `null` for non-LLM spans." }, "responseModel": { "type": [ "string", "null" ], "description": "Model id reported by the provider's response. `null` for non-LLM spans." }, "tokensInput": { "type": "number", "description": "Input tokens consumed by this span." }, "tokensOutput": { "type": "number", "description": "Output tokens produced by this span." }, "tokensCacheRead": { "type": "number", "description": "Tokens served from the provider's prompt cache." }, "tokensCacheCreate": { "type": "number", "description": "Tokens written to the provider's prompt cache." }, "tokensReasoning": { "type": "number", "description": "Reasoning tokens reported by the model." }, "costInputMicrocents": { "type": "number", "description": "Cost of input tokens in microcents (1/1,000,000 USD)." }, "costOutputMicrocents": { "type": "number", "description": "Cost of output tokens in microcents (1/1,000,000 USD)." }, "costTotalMicrocents": { "type": "number", "description": "Total cost in microcents (1/1,000,000 USD)." }, "costIsEstimated": { "type": "boolean", "description": "`true` when the cost was derived from public pricing tables instead of the provider's bill." }, "timeToFirstTokenNs": { "type": "number", "description": "Nanoseconds from the start of the span to its first emitted token. `0` if not measured." }, "isStreaming": { "type": "boolean", "description": "`true` when the span was produced by a streaming LLM call." }, "responseId": { "type": [ "string", "null" ], "description": "Response identifier returned by the LLM. `null` when the provider didn't return one." }, "finishReasons": { "type": "array", "items": { "type": "string" }, "description": "Per-choice finish reasons reported by the LLM provider." }, "scopeName": { "type": "string", "description": "OpenTelemetry instrumentation scope name. Empty when not set." }, "scopeVersion": { "type": "string", "description": "OpenTelemetry instrumentation scope version. Empty when not set." }, "retentionDays": { "type": "integer", "exclusiveMinimum": 0, "description": "Per-span retention override in days. Omitted when the project default applies." }, "ingestedAt": { "type": "string", "description": "ISO-8601 timestamp at which Latitude received this span." }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Free-form metadata attached at ingest time." }, "systemInstructions": { "$ref": "#/components/schemas/GenAISpanSystem" }, "inputMessages": { "type": "array", "items": { "$ref": "#/components/schemas/GenAISpanMessage" }, "description": "Input messages sent into this LLM span, in OpenTelemetry GenAI format." }, "outputMessages": { "type": "array", "items": { "$ref": "#/components/schemas/GenAISpanMessage" }, "description": "Output messages returned by this LLM span, in OpenTelemetry GenAI format." }, "toolDefinitions": { "type": "array", "items": { "$ref": "#/components/schemas/ToolDefinition" }, "description": "Tool/function definitions made available to the LLM for this span." }, "toolCallId": { "type": "string", "description": "Tool-call id this span answers. Empty when the span isn't an `execute_tool` span." }, "toolName": { "type": "string", "description": "Name of the executed tool. Empty when the span isn't an `execute_tool` span." }, "toolInput": { "type": "string", "description": "Stringified arguments passed to the tool. Empty when the span isn't an `execute_tool` span." }, "toolOutput": { "type": "string", "description": "Stringified tool output. Empty when the span isn't an `execute_tool` span." }, "attrString": { "type": "object", "additionalProperties": { "type": "string" }, "description": "OpenTelemetry attributes with string values." }, "attrInt": { "type": "object", "additionalProperties": { "type": "number" }, "description": "OpenTelemetry attributes with integer values." }, "attrFloat": { "type": "object", "additionalProperties": { "type": "number" }, "description": "OpenTelemetry attributes with floating-point values." }, "attrBool": { "type": "object", "additionalProperties": { "type": "boolean" }, "description": "OpenTelemetry attributes with boolean values." }, "resourceString": { "type": "object", "additionalProperties": { "type": "string" }, "description": "OpenTelemetry resource attributes captured at ingest." }, "eventsJson": { "type": "string", "description": "JSON-encoded OpenTelemetry events array. Empty when the span has no events." }, "linksJson": { "type": "string", "description": "JSON-encoded OpenTelemetry span-links array. Empty when the span has no links." } }, "required": [ "organizationId", "projectId", "traceId", "spanId", "parentSpanId", "sessionId", "userId", "simulationId", "apiKeyId", "startTime", "endTime", "name", "serviceName", "kind", "statusCode", "statusMessage", "traceFlags", "traceState", "errorType", "tags", "operation", "provider", "model", "responseModel", "tokensInput", "tokensOutput", "tokensCacheRead", "tokensCacheCreate", "tokensReasoning", "costInputMicrocents", "costOutputMicrocents", "costTotalMicrocents", "costIsEstimated", "timeToFirstTokenNs", "isStreaming", "responseId", "finishReasons", "scopeName", "scopeVersion", "ingestedAt", "metadata", "systemInstructions", "inputMessages", "outputMessages", "toolDefinitions", "toolCallId", "toolName", "toolInput", "toolOutput", "attrString", "attrInt", "attrFloat", "attrBool", "resourceString", "eventsJson", "linksJson" ] }, "GenAISpanSystem": { "type": "array", "items": { "type": "object", "additionalProperties": {} }, "description": "System instructions in OpenTelemetry GenAI format — an array of part objects." }, "GenAISpanMessage": { "type": "object", "additionalProperties": {}, "description": "Message in OpenTelemetry GenAI format (`role` + content parts + optional tool calls)." }, "ToolDefinition": { "type": "object", "properties": { "name": { "type": "string", "description": "Tool name as exposed to the LLM." }, "description": { "type": "string", "description": "Tool description as exposed to the LLM." }, "parameters": { "description": "JSON Schema for the tool's parameters, as provided by the caller." } }, "required": [ "name", "description" ] }, "PaginatedTraceAnnotations": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Annotation" }, "description": "Page of items, in the requested sort order." }, "nextCursor": { "type": [ "string", "null" ], "description": "Opaque cursor for fetching the next page. `null` when there are no more pages. Pass it back in `cursor` to continue." }, "hasMore": { "type": "boolean", "description": "`true` when there is at least one more page after this one." } }, "required": [ "items", "nextCursor", "hasMore" ] }, "ExportTracesResponse": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "queued" ], "description": "Always `\"queued\"`. The CSV is built asynchronously and emailed to `recipient` when ready." } }, "required": [ "status" ] }, "ExportTracesBody": { "type": "object", "properties": { "traces": { "$ref": "#/components/schemas/TracesRef" }, "recipient": { "type": "string", "format": "email", "description": "Email address the export download link is sent to. Must belong to a member of the requesting organization — otherwise the request is rejected with 400." } }, "required": [ "traces", "recipient" ] }, "TracesRef": { "oneOf": [ { "type": "object", "properties": { "by": { "type": "string", "enum": [ "ids" ], "description": "Match an explicit list of traces by their identifiers. Pair with `ids`." }, "ids": { "type": "array", "items": { "type": "string", "minLength": 32, "maxLength": 32, "description": "32-character trace identifier." }, "minItems": 1, "description": "Non-empty list of trace identifiers." } }, "required": [ "by", "ids" ] }, { "type": "object", "properties": { "by": { "type": "string", "enum": [ "filters" ], "description": "Match every trace produced by a filter set. Pair with `filters`; result count is not bounded." }, "filters": { "$ref": "#/components/schemas/FilterSet" } }, "required": [ "by", "filters" ] } ], "description": "Which traces to include in the export — either explicit ids or a filter set." }, "ToolsAnalyticsResponse": { "type": "object", "properties": { "totals": { "$ref": "#/components/schemas/ToolsAnalyticsTotals" }, "tools": { "type": "array", "items": { "$ref": "#/components/schemas/ToolSummary" }, "description": "Every tool in the range — the union of defined and called tools." } }, "required": [ "totals", "tools" ] }, "ToolsAnalyticsTotals": { "type": "object", "properties": { "traces": { "type": "integer", "description": "Total traces in the range." }, "sessions": { "type": "integer", "description": "Total sessions in the range." }, "tracesWithToolCalls": { "type": "integer", "description": "Traces with at least one tool call (any tool)." }, "sessionsWithToolCalls": { "type": "integer", "description": "Sessions with at least one tool call (any tool)." } }, "required": [ "traces", "sessions", "tracesWithToolCalls", "sessionsWithToolCalls" ], "description": "Project-wide denominators for the range." }, "ToolSummary": { "type": "object", "properties": { "name": { "type": "string", "description": "Tool name." }, "metrics": { "$ref": "#/components/schemas/ToolUsageMetrics" }, "offeredCount": { "type": "integer", "description": "LLM turns that offered this tool. 0 means no definition was seen." }, "offeredTraces": { "type": "integer", "description": "Distinct traces that offered this tool." }, "lastOffered": { "type": [ "string", "null" ], "description": "ISO-8601 timestamp the tool was last offered. `null` when never offered." }, "selectionRate": { "type": [ "number", "null" ], "description": "Calls per offer (`calls / offeredCount`). Can exceed 1. `null` when never offered." }, "trend": { "type": "array", "items": { "$ref": "#/components/schemas/ToolCallHistogramBucket" }, "description": "Per-bucket call counts across the range." } }, "required": [ "name", "metrics", "offeredCount", "offeredTraces", "lastOffered", "selectionRate", "trend" ] }, "ToolUsageMetrics": { "type": [ "object", "null" ], "properties": { "calls": { "type": "integer", "description": "Number of times the tool was called in the range." }, "errors": { "type": "integer", "description": "Number of calls that ended in an error." }, "errorRate": { "type": "number", "description": "Fraction of calls that errored, 0..1." }, "avgDurationNs": { "type": "number", "description": "Mean call duration, in nanoseconds." }, "p50DurationNs": { "type": "number", "description": "Median (p50) call duration, in nanoseconds." }, "p95DurationNs": { "type": "number", "description": "95th-percentile call duration, in nanoseconds." }, "p99DurationNs": { "type": "number", "description": "99th-percentile call duration, in nanoseconds." }, "tracesUsed": { "type": "integer", "description": "Distinct traces with at least one call of this tool." }, "sessionsUsed": { "type": "integer", "description": "Distinct sessions with at least one call of this tool." }, "traceUsageRate": { "type": "number", "description": "`tracesUsed` divided by total traces in the range, 0..1." }, "sessionUsageRate": { "type": "number", "description": "`sessionsUsed` divided by total sessions in the range, 0..1." }, "firstSeen": { "type": "string", "description": "ISO-8601 timestamp of the first call in the range." }, "lastUsed": { "type": "string", "description": "ISO-8601 timestamp of the most recent call in the range." } }, "required": [ "calls", "errors", "errorRate", "avgDurationNs", "p50DurationNs", "p95DurationNs", "p99DurationNs", "tracesUsed", "sessionsUsed", "traceUsageRate", "sessionUsageRate", "firstSeen", "lastUsed" ], "description": "Call-side usage metrics. `null` when the tool was defined but never called in the range." }, "ToolCallHistogramBucket": { "type": "object", "properties": { "bucketStart": { "type": "string", "description": "ISO-8601 UTC timestamp of the bucket's start." }, "calls": { "type": "integer", "description": "Number of calls in this bucket." }, "errors": { "type": "integer", "description": "Number of errored calls in this bucket." }, "p50DurationNs": { "type": "number", "description": "Median call duration in this bucket, in nanoseconds." } }, "required": [ "bucketStart", "calls", "errors", "p50DurationNs" ] }, "ToolHistogramResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ToolCallHistogramBucket" }, "description": "Call buckets across the range, oldest first." } }, "required": [ "items" ] }, "ToolParameterStatsResponse": { "type": "object", "properties": { "stats": { "type": "array", "items": { "$ref": "#/components/schemas/ToolParameterStat" }, "description": "Top input keys and their most common values." }, "sampleSize": { "type": "integer", "description": "Number of recent calls the stats were computed over." } }, "required": [ "stats", "sampleSize" ] }, "ToolParameterStat": { "type": "object", "properties": { "key": { "type": "string", "description": "A top-level key in the tool's input." }, "occurrences": { "type": "integer", "description": "Sampled calls whose input contains this key." }, "topValues": { "type": "array", "items": { "$ref": "#/components/schemas/ToolParameterValueStat" }, "description": "Most common values for this key." } }, "required": [ "key", "occurrences", "topValues" ] }, "ToolParameterValueStat": { "type": "object", "properties": { "value": { "type": "string", "description": "A value seen for the key (truncated)." }, "count": { "type": "integer", "description": "Number of sampled calls with this value." } }, "required": [ "value", "count" ] }, "ToolContextBreakdownResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ToolContextBreakdownRow" }, "description": "Breakdown rows, most significant first." } }, "required": [ "items" ] }, "ToolContextBreakdownRow": { "type": "object", "properties": { "value": { "type": "string", "description": "The dimension value (a model, provider, or tag)." }, "traces": { "type": "integer", "description": "Distinct traces for this value." }, "occurrences": { "type": "integer", "description": "Underlying spans or calls behind this value." } }, "required": [ "value", "traces", "occurrences" ] }, "ToolCoOccurrenceResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ToolCoOccurrenceRow" }, "description": "Co-occurring tools, by shared trace count." } }, "required": [ "items" ] }, "ToolCoOccurrenceRow": { "type": "object", "properties": { "otherTool": { "type": "string", "description": "Another tool called in the same traces." }, "sharedTraces": { "type": "integer", "description": "Traces where both tools were called." } }, "required": [ "otherTool", "sharedTraces" ] }, "ToolErrorBreakdownResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ToolErrorBreakdownRow" }, "description": "Error clusters, most frequent first." } }, "required": [ "items" ] }, "ToolErrorBreakdownRow": { "type": "object", "properties": { "key": { "type": "string", "description": "Normalized error cluster key. Empty when the calls carried no error output." }, "sample": { "type": "string", "description": "A verbatim error output from the cluster (truncated)." }, "errorType": { "type": "string", "description": "An error type seen in the cluster." }, "calls": { "type": "integer", "description": "Number of failed calls in the cluster." } }, "required": [ "key", "sample", "errorType", "calls" ] }, "PaginatedToolCalls": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/RecentToolCall" }, "description": "Page of items, in the requested sort order." }, "nextCursor": { "type": [ "string", "null" ], "description": "Opaque cursor for fetching the next page. `null` when there are no more pages. Pass it back in `cursor` to continue." }, "hasMore": { "type": "boolean", "description": "`true` when there is at least one more page after this one." } }, "required": [ "items", "nextCursor", "hasMore" ] }, "RecentToolCall": { "type": "object", "properties": { "spanId": { "type": "string", "description": "16-character span identifier of the tool call." }, "traceId": { "type": "string", "description": "Trace this call belongs to." }, "sessionId": { "type": "string", "description": "Session this call belongs to." }, "startTime": { "type": "string", "description": "ISO-8601 timestamp the call started." }, "durationNs": { "type": "number", "description": "Call duration, in nanoseconds." }, "statusCode": { "type": "string", "enum": [ "unset", "ok", "error" ], "description": "Span status of the call." }, "statusMessage": { "type": "string", "description": "Status message, when present." }, "errorType": { "type": "string", "description": "Error type, when the call failed." }, "toolCallId": { "type": "string", "description": "Provider tool-call id linking the call to its request." }, "toolInput": { "type": "string", "description": "Truncated preview of the call arguments." }, "toolOutput": { "type": "string", "description": "Truncated preview of the call result." }, "toolInputTruncated": { "type": "boolean", "description": "`true` when `toolInput` was truncated." }, "toolOutputTruncated": { "type": "boolean", "description": "`true` when `toolOutput` was truncated." } }, "required": [ "spanId", "traceId", "sessionId", "startTime", "durationNs", "statusCode", "statusMessage", "errorType", "toolCallId", "toolInput", "toolOutput", "toolInputTruncated", "toolOutputTruncated" ] }, "ToolDetailResponse": { "type": "object", "properties": { "definition": { "$ref": "#/components/schemas/ToolDefinitionDetail" }, "usage": { "allOf": [ { "$ref": "#/components/schemas/ToolUsageMetrics" }, { "description": "Global (all-calls) usage metrics. `null` when the tool has no calls in the range." } ] }, "errorsUsage": { "allOf": [ { "$ref": "#/components/schemas/ToolUsageMetrics" }, { "description": "Failed-calls-only usage metrics. Non-null only when `errorsOnly=true` is requested." } ] } }, "required": [ "definition", "usage", "errorsUsage" ] }, "ToolDefinitionDetail": { "type": [ "object", "null" ], "properties": { "definition": { "type": [ "object", "null" ], "properties": { "name": { "type": "string", "description": "Tool name from the definition." }, "description": { "type": "string", "description": "Tool description from the definition." } }, "required": [ "name", "description" ], "description": "Parsed name and description. `null` when the stored definition could not be parsed." }, "definitionJson": { "type": "string", "description": "Raw tool definition JSON, verbatim, including its `parameters`." }, "offeredCount": { "type": "integer", "description": "LLM turns that offered this tool in the range." }, "offeredTraces": { "type": "integer", "description": "Distinct traces that offered this tool." }, "lastOffered": { "type": "string", "description": "ISO-8601 timestamp the tool was last offered." } }, "required": [ "definition", "definitionJson", "offeredCount", "offeredTraces", "lastOffered" ], "description": "Latest definition seen for the tool. `null` when never offered in the range." }, "UserListResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectUser" }, "description": "Page of users, in the requested sort order." }, "totalCount": { "type": "integer", "description": "Total users matching the filters across every page." }, "hasMore": { "type": "boolean", "description": "`true` when there is at least one more page after this one." }, "limit": { "type": "integer", "description": "Page size used for this response." }, "offset": { "type": "integer", "description": "Zero-based offset of the first item in this page." }, "costRollup": { "$ref": "#/components/schemas/UserCostRollup" } }, "required": [ "items", "totalCount", "hasMore", "limit", "offset", "costRollup" ] }, "ProjectUser": { "type": "object", "properties": { "userId": { "type": "string", "description": "The end-user's identifier, as reported on their traces' `user_id`." }, "userEmail": { "type": "string", "description": "Latest non-empty email seen on the user's traces. Empty when never reported." }, "firstSeenAt": { "type": "string", "description": "ISO-8601 timestamp of the user's first trace in the range." }, "lastSeenAt": { "type": "string", "description": "ISO-8601 timestamp of the user's most recent trace in the range." }, "traceCount": { "type": "integer", "description": "Traces attributed to the user in the range." }, "sessionCount": { "type": "integer", "description": "Distinct sessions in which the user produced at least one trace." }, "errorSessionCount": { "type": "integer", "description": "Of `sessionCount`, sessions with at least one errored trace." }, "tokensTotal": { "type": "integer", "description": "Total tokens across the user's traces." }, "costTotalMicrocents": { "type": "number", "description": "Total cost across the user's traces, in microcents." }, "costAvgMicrocents": { "type": "number", "description": "Mean per-trace cost across the user's traces, in microcents." }, "costMedianMicrocents": { "type": "number", "description": "Median (p50) per-trace cost across the user's traces, in microcents." } }, "required": [ "userId", "userEmail", "firstSeenAt", "lastSeenAt", "traceCount", "sessionCount", "errorSessionCount", "tokensTotal", "costTotalMicrocents", "costAvgMicrocents", "costMedianMicrocents" ] }, "UserCostRollup": { "type": "object", "properties": { "sum": { "type": "number", "description": "Sum of every matching user's total cost, in microcents." }, "avg": { "type": "number", "description": "Mean of every matching user's mean per-trace cost, in microcents." }, "median": { "type": "number", "description": "Median of every matching user's median per-trace cost, in microcents." } }, "required": [ "sum", "avg", "median" ], "description": "Cost aggregates across every matching user, not just this page." }, "UsersOverviewResponse": { "type": "object", "properties": { "uniqueUsers": { "type": "integer", "description": "Distinct identified users with at least one trace in the range." }, "newUsers": { "type": "integer", "description": "Users whose first trace ever falls inside the range." }, "identifiedTraces": { "type": "integer", "description": "Traces in the range carrying a non-empty `user_id`." }, "totalTraces": { "type": "integer", "description": "All traces in the range, identified or not." }, "identifiedSessions": { "type": "integer", "description": "Distinct sessions in the range carrying a non-empty `user_id`." }, "totalSessions": { "type": "integer", "description": "All distinct sessions in the range, identified or not." }, "histogram": { "type": "array", "items": { "$ref": "#/components/schemas/UsersOverviewBucket" }, "description": "Per-bucket activity across the range, oldest first." }, "bucketSeconds": { "type": "integer", "description": "Bucket width the histogram was computed with, in seconds." }, "fromIso": { "type": "string", "description": "ISO-8601 lower bound of the resolved range." }, "toIso": { "type": "string", "description": "ISO-8601 upper bound of the resolved range." } }, "required": [ "uniqueUsers", "newUsers", "identifiedTraces", "totalTraces", "identifiedSessions", "totalSessions", "histogram", "bucketSeconds", "fromIso", "toIso" ] }, "UsersOverviewBucket": { "type": "object", "properties": { "bucket": { "type": "string", "description": "ISO-8601 UTC timestamp of the bucket's start." }, "activeUsers": { "type": "integer", "description": "Distinct identified users active in the bucket." }, "traceCount": { "type": "integer", "description": "Identified traces in the bucket." }, "sessionCount": { "type": "integer", "description": "Distinct user-attributed sessions starting in the bucket." }, "errorSessionCount": { "type": "integer", "description": "Of `sessionCount`, those with at least one errored trace." } }, "required": [ "bucket", "activeUsers", "traceCount", "sessionCount", "errorSessionCount" ] }, "UserActivityResponse": { "type": "object", "properties": { "buckets": { "type": "array", "items": { "$ref": "#/components/schemas/UserActivityBucket" }, "description": "Per-bucket session activity across the range, oldest first." }, "bucketSeconds": { "type": "integer", "description": "Bucket width the buckets were computed with, in seconds." }, "fromIso": { "type": "string", "description": "ISO-8601 lower bound of the resolved range." }, "toIso": { "type": "string", "description": "ISO-8601 upper bound of the resolved range." } }, "required": [ "buckets", "bucketSeconds", "fromIso", "toIso" ] }, "UserActivityBucket": { "type": "object", "properties": { "bucket": { "type": "string", "description": "ISO-8601 UTC timestamp of the bucket's start." }, "count": { "type": "integer", "description": "Distinct user-attributed sessions starting in the bucket." }, "errorCount": { "type": "integer", "description": "Of `count`, sessions with at least one errored trace." } }, "required": [ "bucket", "count", "errorCount" ] }, "UserUsageResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/UserUsageSlice" }, "description": "Top dimension values, by distinct trace count, most used first." } }, "required": [ "items" ] }, "UserUsageSlice": { "type": "object", "properties": { "value": { "type": "string", "description": "A value of the requested dimension (a model, provider, or tool name)." }, "traceCount": { "type": "integer", "description": "Distinct traces of the user carrying this value." } }, "required": [ "value", "traceCount" ] }, "UserSignalsResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/UserSignal" }, "description": "Signals seen on the user's traces, most recent occurrence first." } }, "required": [ "items" ] }, "UserSignal": { "type": "object", "properties": { "signalId": { "type": "string", "description": "Stable identifier of the signal." }, "name": { "type": "string", "description": "Human-readable signal name." }, "description": { "type": "string", "description": "Signal description." }, "states": { "type": "array", "items": { "type": "string" }, "description": "Lifecycle states currently applying to the signal." }, "priority": { "type": [ "string", "null" ], "description": "Signal priority. `null` when unset." }, "occurrences": { "type": "integer", "description": "Occurrences on the user's traces." }, "affectedTraces": { "type": "integer", "description": "Distinct traces of the user that contributed an occurrence." }, "firstSeenAt": { "type": "string", "description": "ISO-8601 timestamp of the first occurrence on the user's traces." }, "lastSeenAt": { "type": "string", "description": "ISO-8601 timestamp of the most recent occurrence on the user's traces." } }, "required": [ "signalId", "name", "description", "states", "priority", "occurrences", "affectedTraces", "firstSeenAt", "lastSeenAt" ] }, "UserBehavioursResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/UserBehaviour" }, "description": "Behaviour clusters observed on the user's sessions, most frequent first." } }, "required": [ "items" ] }, "UserBehaviour": { "type": "object", "properties": { "clusterId": { "type": "string", "description": "Stable identifier of the behaviour cluster." }, "name": { "type": "string", "description": "Human-readable behaviour name." }, "description": { "type": "string", "description": "Behaviour description." }, "observationCount": { "type": "integer", "description": "Observations of this behaviour on the user's sessions." }, "firstObservedAt": { "type": "string", "description": "ISO-8601 timestamp the behaviour was first observed for the user." }, "lastObservedAt": { "type": "string", "description": "ISO-8601 timestamp the behaviour was last observed for the user." } }, "required": [ "clusterId", "name", "description", "observationCount", "firstObservedAt", "lastObservedAt" ] }, "UserProfileResponse": { "type": "object", "properties": { "userId": { "type": "string", "description": "The end-user's identifier, as reported on their traces' `user_id`." }, "userEmail": { "type": "string", "description": "Latest non-empty email seen on the user's traces. Empty when never reported." }, "firstSeenAt": { "type": "string", "description": "ISO-8601 timestamp of the user's first trace ever." }, "lastSeenAt": { "type": "string", "description": "ISO-8601 timestamp of the user's most recent trace ever." }, "traceCount": { "type": "integer", "description": "Lifetime traces attributed to the user." }, "sessionCount": { "type": "integer", "description": "Distinct sessions in which the user produced at least one trace." }, "errorSessionCount": { "type": "integer", "description": "Of `sessionCount`, sessions with at least one errored trace." }, "tokensTotal": { "type": "integer", "description": "Total tokens across the user's traces." }, "tokensInput": { "type": "integer", "description": "Input (prompt) tokens across the user's traces." }, "tokensOutput": { "type": "integer", "description": "Output (completion) tokens across the user's traces." }, "costTotalMicrocents": { "type": "number", "description": "Total cost across the user's traces, in microcents." }, "avgDurationNs": { "type": "number", "description": "Mean per-trace duration, in nanoseconds." }, "activeDays": { "type": "integer", "description": "Distinct UTC days with at least one trace." } }, "required": [ "userId", "userEmail", "firstSeenAt", "lastSeenAt", "traceCount", "sessionCount", "errorSessionCount", "tokensTotal", "tokensInput", "tokensOutput", "costTotalMicrocents", "avgDurationNs", "activeDays" ] }, "PaginatedSavedSearches": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/SavedSearch" }, "description": "Page of items, in the requested sort order." }, "nextCursor": { "type": [ "string", "null" ], "description": "Opaque cursor for fetching the next page. `null` when there are no more pages. Pass it back in `cursor` to continue." }, "hasMore": { "type": "boolean", "description": "`true` when there is at least one more page after this one." } }, "required": [ "items", "nextCursor", "hasMore" ] }, "SavedSearch": { "type": "object", "properties": { "id": { "type": "string", "minLength": 24, "maxLength": 24, "description": "Stable saved-search identifier." }, "organizationId": { "type": "string", "minLength": 24, "maxLength": 24, "description": "Organization that owns this saved search." }, "projectId": { "type": "string", "minLength": 24, "maxLength": 24, "description": "Project this saved search belongs to." }, "slug": { "type": "string", "description": "URL-safe slug derived from `name`. Regenerated when the name changes in a way that affects the slug." }, "name": { "type": "string", "description": "Human-readable name." }, "query": { "type": [ "string", "null" ], "description": "Free-text semantic query applied alongside `filters`. `null` when the search is filter-only. At least one of `query` or `filters` must be set." }, "filters": { "allOf": [ { "$ref": "#/components/schemas/FilterSet" }, { "description": "Structured filter set applied alongside `query`. Empty object means filter-free. At least one of `query` or `filters` must be set." } ] }, "deletedAt": { "type": [ "string", "null" ], "description": "ISO-8601 timestamp at which the search was deleted. `null` while active." }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp of creation." }, "updatedAt": { "type": "string", "description": "ISO-8601 timestamp of the last update." } }, "required": [ "id", "organizationId", "projectId", "slug", "name", "query", "filters", "deletedAt", "createdAt", "updatedAt" ] }, "CreateSavedSearchBody": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Human-readable name. Used to derive the slug." }, "query": { "type": [ "string", "null" ], "maxLength": 500, "default": null, "description": "Free-text semantic query. `null` (default) when the search is filter-only. At least one of `query` or `filters` must be set." }, "filters": { "allOf": [ { "$ref": "#/components/schemas/FilterSet" }, { "description": "Structured filter set. Defaults to `{}` (no filters). At least one of `query` or `filters` must be set." } ] } }, "required": [ "name" ] }, "UpdateSavedSearchBody": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 256, "description": "New human-readable name. Triggers slug regeneration when the change affects the slug form (cosmetic edits like capitalization keep the URL stable)." }, "query": { "type": [ "string", "null" ], "maxLength": 500, "description": "Replace the free-text query. Pass `null` to clear it." }, "filters": { "allOf": [ { "$ref": "#/components/schemas/FilterSet" }, { "description": "Replace the structured filter set." } ] } } }, "PaginatedSignals": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Signal" }, "description": "Page of items, in the requested sort order." }, "nextCursor": { "type": [ "string", "null" ], "description": "Opaque cursor for fetching the next page. `null` when there are no more pages. Pass it back in `cursor` to continue." }, "hasMore": { "type": "boolean", "description": "`true` when there is at least one more page after this one." } }, "required": [ "items", "nextCursor", "hasMore" ] }, "Signal": { "type": "object", "properties": { "id": { "type": "string", "minLength": 24, "maxLength": 24, "description": "Stable signal identifier." }, "organizationId": { "type": "string", "minLength": 24, "maxLength": 24, "description": "Organization that owns this signal." }, "projectId": { "type": "string", "minLength": 24, "maxLength": 24, "description": "Project this signal belongs to." }, "slug": { "type": "string", "description": "URL-safe slug derived from `name`. Unique within the project." }, "name": { "type": "string", "description": "Human-readable name." }, "description": { "type": "string", "description": "Description of the signal." }, "source": { "type": "string", "enum": [ "annotation", "flagger", "custom" ], "description": "Where the signal originated from." }, "states": { "type": "array", "items": { "type": "string", "enum": [ "new", "escalating", "ongoing", "resolved", "regressed", "ignored" ] }, "description": "Active lifecycle states. A signal may carry multiple states at once (e.g. `escalating` + `ongoing`)." }, "resolvedAt": { "type": [ "string", "null" ], "description": "ISO-8601 timestamp at which the signal was resolved, or `null`." }, "ignoredAt": { "type": [ "string", "null" ], "description": "ISO-8601 timestamp at which the signal was ignored, or `null`." }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp of creation." }, "updatedAt": { "type": "string", "description": "ISO-8601 timestamp of the last update." }, "trend": { "type": "array", "items": { "$ref": "#/components/schemas/SignalTrendBucket" }, "description": "Daily occurrence counts over the past 14 days." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags seen on the signal's occurrences." }, "firstSeenAt": { "type": "string", "description": "ISO-8601 timestamp of the earliest occurrence in the time window." }, "lastSeenAt": { "type": "string", "description": "ISO-8601 timestamp of the latest occurrence in the time window." }, "occurrences": { "type": "integer", "minimum": 0, "description": "Number of occurrences in the time window." }, "affectedTracesPercent": { "type": "number", "minimum": 0, "maximum": 1, "description": "Fraction of project traces affected by this signal in the time window, in `[0, 1]`." } }, "required": [ "id", "organizationId", "projectId", "slug", "name", "description", "source", "states", "resolvedAt", "ignoredAt", "createdAt", "updatedAt", "trend", "tags", "firstSeenAt", "lastSeenAt", "occurrences", "affectedTracesPercent" ] }, "SignalTrendBucket": { "type": "object", "properties": { "bucket": { "type": "string", "description": "UTC day bucket (`YYYY-MM-DD`)." }, "count": { "type": "integer", "minimum": 0, "description": "Number of occurrences within the bucket." } }, "required": [ "bucket", "count" ] }, "SignalAnalyticsResponse": { "type": "object", "properties": { "ongoing": { "$ref": "#/components/schemas/SignalAnalyticsOngoing" }, "new": { "$ref": "#/components/schemas/SignalAnalyticsNew" }, "escalating": { "$ref": "#/components/schemas/SignalAnalyticsEscalating" }, "regressed": { "$ref": "#/components/schemas/SignalAnalyticsRegressed" }, "resolved": { "$ref": "#/components/schemas/SignalAnalyticsResolved" }, "occurrences": { "$ref": "#/components/schemas/SignalAnalyticsOccurrences" } }, "required": [ "ongoing", "new", "escalating", "regressed", "resolved", "occurrences" ] }, "SignalAnalyticsOngoing": { "type": "object", "properties": { "total": { "type": "integer", "minimum": 0, "description": "Number of ongoing signals." } }, "required": [ "total" ] }, "SignalAnalyticsNew": { "type": "object", "properties": { "total": { "type": "integer", "minimum": 0, "description": "Number of new signals." } }, "required": [ "total" ] }, "SignalAnalyticsEscalating": { "type": "object", "properties": { "total": { "type": "integer", "minimum": 0, "description": "Number of escalating signals." } }, "required": [ "total" ] }, "SignalAnalyticsRegressed": { "type": "object", "properties": { "total": { "type": "integer", "minimum": 0, "description": "Number of regressed signals." } }, "required": [ "total" ] }, "SignalAnalyticsResolved": { "type": "object", "properties": { "total": { "type": "integer", "minimum": 0, "description": "Number of resolved signals." } }, "required": [ "total" ] }, "SignalAnalyticsOccurrences": { "type": "object", "properties": { "total": { "type": "integer", "minimum": 0, "description": "Number of signal occurrences in the range." }, "buckets": { "type": "array", "items": { "$ref": "#/components/schemas/SignalAnalyticsBucket" }, "description": "Number of signal occurrences per bucket." } }, "required": [ "total", "buckets" ] }, "SignalAnalyticsBucket": { "type": "object", "properties": { "bucket": { "type": "string", "description": "ISO-8601 UTC timestamp of the bucket's start." }, "value": { "type": "integer", "minimum": 0, "description": "Number of occurrences in this bucket." } }, "required": [ "bucket", "value" ] }, "SignalDetail": { "type": "object", "properties": { "id": { "type": "string", "minLength": 24, "maxLength": 24, "description": "Stable signal identifier." }, "organizationId": { "type": "string", "minLength": 24, "maxLength": 24, "description": "Organization that owns this signal." }, "projectId": { "type": "string", "minLength": 24, "maxLength": 24, "description": "Project this signal belongs to." }, "slug": { "type": "string", "description": "URL-safe slug derived from `name`. Unique within the project." }, "name": { "type": "string", "description": "Human-readable name." }, "description": { "type": "string", "description": "Description of the signal." }, "source": { "type": "string", "enum": [ "annotation", "flagger", "custom" ], "description": "Where the signal originated from." }, "states": { "type": "array", "items": { "type": "string", "enum": [ "new", "escalating", "ongoing", "resolved", "regressed", "ignored" ] }, "description": "Active lifecycle states. A signal may carry multiple states at once (e.g. `escalating` + `ongoing`)." }, "resolvedAt": { "type": [ "string", "null" ], "description": "ISO-8601 timestamp at which the signal was resolved, or `null`." }, "ignoredAt": { "type": [ "string", "null" ], "description": "ISO-8601 timestamp at which the signal was ignored, or `null`." }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp of creation." }, "updatedAt": { "type": "string", "description": "ISO-8601 timestamp of the last update." }, "trend": { "type": "array", "items": { "$ref": "#/components/schemas/SignalTrendBucket" }, "description": "Daily occurrence counts over the past 14 days." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags seen on the signal's occurrences." }, "firstSeenAt": { "type": [ "string", "null" ], "description": "ISO-8601 timestamp of the earliest occurrence over the signal's lifetime, or `null` if none yet." }, "lastSeenAt": { "type": [ "string", "null" ], "description": "ISO-8601 timestamp of the latest occurrence over the signal's lifetime, or `null` if none yet." }, "occurrences": { "type": "integer", "minimum": 0, "description": "Lifetime occurrence count." }, "affectedTracesPercent": { "type": "number", "minimum": 0, "maximum": 1, "description": "Lifetime fraction of project traces affected by this signal, in `[0, 1]`." }, "evaluations": { "type": "array", "items": { "$ref": "#/components/schemas/Evaluation" }, "description": "Active evaluations monitoring the signal. Archived and deleted evaluations are excluded." }, "monitoringState": { "$ref": "#/components/schemas/SignalMonitoringState" } }, "required": [ "id", "organizationId", "projectId", "slug", "name", "description", "source", "states", "resolvedAt", "ignoredAt", "createdAt", "updatedAt", "trend", "tags", "firstSeenAt", "lastSeenAt", "occurrences", "affectedTracesPercent", "evaluations", "monitoringState" ] }, "Evaluation": { "type": "object", "properties": { "id": { "type": "string", "minLength": 24, "maxLength": 24, "description": "Stable evaluation identifier." }, "name": { "type": "string", "description": "Human-readable name." }, "description": { "type": "string", "description": "Generated description of the evaluation." }, "alignedAt": { "type": "string", "description": "ISO-8601 timestamp at which the evaluation was last realigned." }, "archivedAt": { "type": [ "string", "null" ], "description": "ISO-8601 timestamp at which the evaluation was archived, or `null`." }, "deletedAt": { "type": [ "string", "null" ], "description": "ISO-8601 timestamp at which the evaluation was deleted, or `null`." }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp of creation." }, "updatedAt": { "type": "string", "description": "ISO-8601 timestamp of the last update." }, "sampling": { "type": "number", "minimum": 0, "maximum": 100, "description": "Sampling rate as a percentage in `[0, 100]`. `0` means the evaluation is paused." }, "alignment": { "$ref": "#/components/schemas/EvaluationAlignmentMetrics" } }, "required": [ "id", "name", "description", "alignedAt", "archivedAt", "deletedAt", "createdAt", "updatedAt", "sampling", "alignment" ] }, "EvaluationAlignmentMetrics": { "type": "object", "properties": { "alignmentMetric": { "type": "number", "description": "Headline score that judges how well the evaluation tracks human annotations." }, "accuracy": { "type": "number", "description": "Accuracy: `(TP + TN) / total`." }, "precision": { "type": "number", "description": "Precision: `TP / (TP + FP)`." }, "recall": { "type": "number", "description": "Recall / sensitivity: `TP / (TP + FN)`." }, "specificity": { "type": "number", "description": "Specificity: `TN / (TN + FP)`." }, "trueness": { "type": "number", "description": "Mean of precision and negative predictive value." }, "f1": { "type": "number", "description": "F1 score: harmonic mean of precision and recall." }, "balancedAccuracy": { "type": "number", "description": "Balanced accuracy: mean of recall and specificity." }, "matthewsCorrelationCoefficient": { "type": "number", "description": "Matthews correlation coefficient, in `[-1, 1]`." } }, "required": [ "alignmentMetric", "accuracy", "precision", "recall", "specificity", "trueness", "f1", "balancedAccuracy", "matthewsCorrelationCoefficient" ], "description": "Alignment metrics computed from the evaluation's confusion matrix." }, "SignalMonitoringState": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "automatic" ] } }, "required": [ "kind" ], "description": "The signal is automatically monitored by the system and does not need an evaluation." }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "idle" ] } }, "required": [ "kind" ], "description": "The signal is not currently being monitored." }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "generating" ] } }, "required": [ "kind" ], "description": "An evaluation is being generated for this signal. The signal has no active evaluation yet." }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "realigning" ] }, "evaluationId": { "type": "string", "minLength": 24, "maxLength": 24, "description": "Id of the evaluation currently being realigned." } }, "required": [ "kind", "evaluationId" ], "description": "An active evaluation is being realigned." } ], "description": "Whether the signal is currently being monitored: `automatic`, `idle`, `generating`, or `realigning`." }, "SignalHistogram": { "type": "object", "properties": { "buckets": { "type": "array", "items": { "$ref": "#/components/schemas/SignalHistogramBucket" }, "description": "One entry per 12-hour UTC-aligned bucket in the requested range, including empty buckets (`count: 0`)." } }, "required": [ "buckets" ] }, "SignalHistogramBucket": { "type": "object", "properties": { "bucket": { "type": "string", "description": "ISO-8601 UTC timestamp of the bucket's start." }, "count": { "type": "integer", "minimum": 0, "description": "Number of occurrences within the bucket." } }, "required": [ "bucket", "count" ] }, "SignalsLifecycleResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/SignalLifecycleItem" }, "description": "Per-signal result, in the order requested." } }, "required": [ "items" ] }, "SignalLifecycleItem": { "type": "object", "properties": { "signalId": { "type": "string", "minLength": 24, "maxLength": 24, "description": "Signal this entry applies to." }, "resolvedAt": { "type": [ "string", "null" ], "description": "ISO-8601 timestamp at which the signal was resolved, or `null`." }, "ignoredAt": { "type": [ "string", "null" ], "description": "ISO-8601 timestamp at which the signal was ignored, or `null`." }, "updatedAt": { "type": "string", "description": "ISO-8601 timestamp of the last update." }, "changed": { "type": "boolean", "description": "`true` when this call changed the signal, `false` when it was already in that state." } }, "required": [ "signalId", "resolvedAt", "ignoredAt", "updatedAt", "changed" ] }, "ResolveSignalsBody": { "allOf": [ { "$ref": "#/components/schemas/SignalsLifecycleBody" }, { "type": "object", "properties": { "keepMonitoring": { "type": "boolean", "description": "When `true`, monitoring continues after the signals are resolved. When `false`, monitoring stops. Defaults to the project setting." } } } ] }, "SignalsLifecycleBody": { "type": "object", "properties": { "signalIds": { "type": "array", "items": { "type": "string", "minLength": 24, "maxLength": 24 }, "minItems": 1, "description": "Non-empty list of signal ids. Operations are idempotent — already-applied signals are unchanged." } }, "required": [ "signalIds" ] }, "MonitorSignalResponse": { "type": "object", "properties": { "jobId": { "type": "string", "minLength": 24, "maxLength": 24, "description": "Identifier of the monitor job." }, "evaluationId": { "type": [ "string", "null" ], "minLength": 24, "maxLength": 24, "description": "The id of the evaluation being realigned, or `null` when a brand-new evaluation is being generated." } }, "required": [ "jobId", "evaluationId" ] }, "ExportSignalsResponse": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "queued" ], "description": "Always `\"queued\"`. The CSV is emailed to `recipient` when ready." } }, "required": [ "status" ] }, "ExportSignalsBody": { "type": "object", "properties": { "recipient": { "type": "string", "format": "email", "description": "Email address the download link is sent to. Must belong to a member of the requesting organization." }, "signalIds": { "type": "array", "items": { "type": "string", "minLength": 24, "maxLength": 24 }, "description": "Restrict the export to this subset of signals. Omit to export every signal in the project." }, "lifecycleGroup": { "type": "string", "enum": [ "active", "archived" ], "description": "`\"active\"` for unresolved/unignored signals; `\"archived\"` for the rest. Omit to include both." } }, "required": [ "recipient" ] }, "ListIncidentsResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Incident" }, "description": "Incidents matching the filters, ordered by `startedAt` ascending." } }, "required": [ "items" ] }, "Incident": { "type": "object", "properties": { "id": { "type": "string", "minLength": 24, "maxLength": 24, "description": "Stable incident identifier." }, "organizationId": { "type": "string", "minLength": 24, "maxLength": 24, "description": "Organization that owns this incident." }, "projectId": { "type": "string", "minLength": 24, "maxLength": 24, "description": "Project this incident belongs to." }, "sourceType": { "type": "string", "enum": [ "issue", "savedSearch" ], "description": "Kind of entity that triggered the incident. `issue` for signal-lifecycle incidents; `savedSearch` for incidents raised by a monitor watching a search." }, "sourceId": { "type": "string", "minLength": 24, "maxLength": 24, "description": "Id of the entity that triggered the incident (matches `sourceType`)." }, "kind": { "type": "string", "enum": [ "issue.new", "issue.regressed", "issue.escalating", "savedSearch.match", "savedSearch.threshold", "savedSearch.escalating", "event.matched", "metric.threshold", "metric.escalating" ], "description": "Reason the incident opened. `issue.new` fires when a new signal is discovered; `issue.regressed` when a resolved signal is detected again; `issue.escalating` when an ongoing signal is being detected more than expected. The `savedSearch.*` kinds are raised by monitors watching a search: `savedSearch.match` on each new matching trace, `savedSearch.threshold` when matching traces are detected above a configured threshold, and `savedSearch.escalating` when they stay above the threshold for a sustained window." }, "severity": { "type": "string", "enum": [ "low", "medium", "high" ], "description": "Severity bucket assigned to the incident: `low`, `medium`, or `high`." }, "startedAt": { "type": "string", "description": "ISO-8601 timestamp at which the incident opened." }, "endedAt": { "type": [ "string", "null" ], "description": "ISO-8601 timestamp at which the incident closed, or `null` if still open." }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp at which the incident row was created." }, "monitorAlertId": { "type": [ "string", "null" ], "minLength": 24, "maxLength": 24, "description": "Id of the monitor alert that opened this incident, or `null` when not attributed to a monitor." }, "condition": { "$ref": "#/components/schemas/AlertCondition" } }, "required": [ "id", "organizationId", "projectId", "sourceType", "sourceId", "kind", "severity", "startedAt", "endedAt", "createdAt", "monitorAlertId", "condition" ] }, "AlertCondition": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "savedSearch.threshold" ], "description": "Threshold alert: opens once the count threshold is crossed." }, "threshold": { "$ref": "#/components/schemas/AlertCountThreshold" } }, "required": [ "kind", "threshold" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "savedSearch.escalating" ], "description": "Sustained alert: opens only when the threshold stays crossed for the whole `window`." }, "threshold": { "$ref": "#/components/schemas/AlertCountThreshold" }, "window": { "type": "object", "properties": { "minutes": { "type": "integer", "minimum": 5, "description": "How long the threshold must stay crossed before the incident opens. The incident stays open while the threshold keeps holding over this window and closes once it no longer does. Minimum 5." } }, "required": [ "minutes" ], "description": "Sustained-condition window." } }, "required": [ "kind", "threshold", "window" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "issue.escalating" ], "description": "System signal-escalation alert; only `sensitivity` is tunable." }, "sensitivity": { "type": "integer", "minimum": 1, "maximum": 6, "description": "Detector sensitivity from 1 (noisiest) to 6 (strictest). Defaults to 3 when omitted." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "metric.threshold" ], "description": "Metric alert: opens once the target metric crosses a threshold." }, "metric": { "$ref": "#/components/schemas/MonitorMetric" }, "threshold": { "$ref": "#/components/schemas/AlertMetricThreshold" }, "direction": { "type": "string", "enum": [ "above", "below" ], "description": "Direction that opens the incident. Defaults to `above` when omitted." } }, "required": [ "kind", "metric", "threshold" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "metric.escalating" ], "description": "Sustained metric alert: opens when the target metric stays across threshold for the whole `window`." }, "metric": { "$ref": "#/components/schemas/MonitorMetric" }, "threshold": { "$ref": "#/components/schemas/AlertMetricThreshold" }, "direction": { "type": "string", "enum": [ "above", "below" ], "description": "Direction that opens the incident. Defaults to `above` when omitted." }, "window": { "type": "object", "properties": { "minutes": { "type": "integer", "minimum": 5, "description": "How long the threshold must stay crossed before the incident opens. Minimum 5." } }, "required": [ "minutes" ], "description": "Sustained-condition window." } }, "required": [ "kind", "metric", "threshold", "window" ] }, { "type": "null" } ], "description": "The alert's configuration when the incident opened, or `null` for kinds with no parameters." }, "AlertCountThreshold": { "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "absolute" ], "description": "Compare the match count against a fixed number; read `count`." }, "count": { "type": "integer", "exclusiveMinimum": 0, "description": "Number of matching traces that opens the incident." } }, "required": [ "mode", "count" ] }, { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "multiplier" ], "description": "Compare the match rate against `factor × baseline`; read `factor` and `baseline`." }, "factor": { "type": "number", "exclusiveMinimum": 0, "description": "Multiple of the baseline rate that opens the incident (e.g. `3` = 3×)." }, "baseline": { "$ref": "#/components/schemas/AlertBaseline" } }, "required": [ "mode", "factor", "baseline" ] }, { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "expected" ], "description": "Compare against the seasonally-learned expected rate for this time of day/week (the same detector as automatic issue escalation); the only knob is `sensitivity`." }, "sensitivity": { "type": "integer", "minimum": 1, "maximum": 6, "description": "Detector sensitivity from 1 (noisiest) to 6 (strictest). Defaults to 3 when omitted." } }, "required": [ "mode" ] } ], "description": "How the match count/rate is compared." }, "AlertBaseline": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "average", "period" ], "description": "How the comparison rate is computed. `average` is the rolling rate over the last `lookback`; `period` is the equal-length window immediately before it (e.g. `lookback` of 1 day compares against yesterday) for daily/weekly seasonality." }, "lookback": { "$ref": "#/components/schemas/AlertDuration" } }, "required": [ "kind", "lookback" ], "description": "Fixed-window baseline the current rate is compared against." }, "AlertDuration": { "oneOf": [ { "type": "object", "properties": { "unit": { "type": "string", "enum": [ "minutes" ], "description": "The duration is expressed in whole minutes; read `minutes`." }, "minutes": { "type": "number", "exclusiveMinimum": 0, "description": "Number of minutes." } }, "required": [ "unit", "minutes" ] }, { "type": "object", "properties": { "unit": { "type": "string", "enum": [ "hours" ], "description": "The duration is expressed in whole hours; read `hours`." }, "hours": { "type": "number", "exclusiveMinimum": 0, "description": "Number of hours." } }, "required": [ "unit", "hours" ] }, { "type": "object", "properties": { "unit": { "type": "string", "enum": [ "days" ], "description": "The duration is expressed in whole days; read `days`." }, "days": { "type": "number", "exclusiveMinimum": 0, "description": "Number of days." } }, "required": [ "unit", "days" ] } ], "description": "Length of the window used to compute the baseline rate." }, "MonitorMetric": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "count" ], "description": "Count matching events in each evaluation bucket." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "errorRate" ], "description": "Measure the fraction of matching events that errored." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "avg" ], "description": "Average a numeric field over matching events." }, "field": { "type": "string", "enum": [ "duration", "cost", "tokens" ], "description": "Numeric field to aggregate." } }, "required": [ "kind", "field" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "p95" ], "description": "Compute the 95th percentile of a numeric field over matching events." }, "field": { "type": "string", "enum": [ "duration", "cost", "tokens" ], "description": "Numeric field to aggregate." } }, "required": [ "kind", "field" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "sum" ], "description": "Sum a numeric field over matching events." }, "field": { "type": "string", "enum": [ "duration", "cost", "tokens" ], "description": "Numeric field to aggregate." } }, "required": [ "kind", "field" ] } ], "description": "Metric measured over the monitor target." }, "AlertMetricThreshold": { "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "absolute" ], "description": "Compare the metric against a fixed value; read `value`." }, "value": { "type": "number", "exclusiveMinimum": 0, "description": "Metric value that opens the incident." } }, "required": [ "mode", "value" ] }, { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "multiplier" ], "description": "Compare the metric rate against `factor × baseline`; read `factor` and `baseline`." }, "factor": { "type": "number", "exclusiveMinimum": 0, "description": "Multiple of the baseline rate that opens the incident (e.g. `3` = 3×)." }, "baseline": { "$ref": "#/components/schemas/AlertBaseline" } }, "required": [ "mode", "factor", "baseline" ] }, { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "expected" ], "description": "Compare against the seasonally-learned expected value for this time of day/week." }, "sensitivity": { "type": "integer", "minimum": 1, "maximum": 6, "description": "Detector sensitivity from 1 (noisiest) to 6 (strictest). Defaults to 3 when omitted." } }, "required": [ "mode" ] } ], "description": "How the metric is compared." }, "PaginatedDatasets": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Dataset" }, "description": "Page of items, in the requested sort order." }, "nextCursor": { "type": [ "string", "null" ], "description": "Opaque cursor for fetching the next page. `null` when there are no more pages. Pass it back in `cursor` to continue." }, "hasMore": { "type": "boolean", "description": "`true` when there is at least one more page after this one." } }, "required": [ "items", "nextCursor", "hasMore" ] }, "Dataset": { "type": "object", "properties": { "id": { "type": "string", "minLength": 24, "maxLength": 24, "description": "Stable dataset identifier." }, "organizationId": { "type": "string", "minLength": 24, "maxLength": 24, "description": "Organization that owns this dataset." }, "projectId": { "type": "string", "minLength": 24, "maxLength": 24, "description": "Project this dataset belongs to." }, "slug": { "type": "string", "description": "URL-safe slug derived from `name`. Unique within the project." }, "name": { "type": "string", "description": "Human-readable name." }, "description": { "type": [ "string", "null" ], "description": "Free-form description, or `null` when not set." }, "version": { "type": "integer", "minimum": 0, "description": "Current dataset version." }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp of creation." }, "updatedAt": { "type": "string", "description": "ISO-8601 timestamp of the last update." } }, "required": [ "id", "organizationId", "projectId", "slug", "name", "description", "version", "createdAt", "updatedAt" ] }, "CreateDatasetBody": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Human-readable name. Used to derive the slug." }, "description": { "type": "string", "description": "Free-form description. Defaults to `null` when omitted or empty." } }, "required": [ "name" ] }, "UpdateDatasetBody": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "New human-readable name. Renaming regenerates the slug." }, "description": { "type": [ "string", "null" ], "description": "New description. Pass `null` to clear; omit to keep the current value." } } }, "PaginatedDatasetRows": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/DatasetRow" }, "description": "Page of items, in the requested sort order." }, "nextCursor": { "type": [ "string", "null" ], "description": "Opaque cursor for fetching the next page. `null` when there are no more pages. Pass it back in `cursor` to continue." }, "hasMore": { "type": "boolean", "description": "`true` when there is at least one more page after this one." } }, "required": [ "items", "nextCursor", "hasMore" ] }, "DatasetRow": { "type": "object", "properties": { "rowId": { "type": "string", "description": "Stable row identifier." }, "datasetId": { "type": "string", "minLength": 24, "maxLength": 24, "description": "Dataset this row belongs to." }, "input": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": {} }, { "type": "object", "additionalProperties": {} } ], "description": "Free-form cell value: any JSON scalar, array, or object." }, "output": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": {} }, { "type": "object", "additionalProperties": {} } ], "description": "Free-form cell value: any JSON scalar, array, or object." }, "expectedOutput": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": {} }, { "type": "object", "additionalProperties": {} } ], "description": "The correct answer for this row. Curators fill this in by hand; it is not derived from `output`." }, "metadata": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": {} }, { "type": "object", "additionalProperties": {} } ], "description": "Free-form cell value: any JSON scalar, array, or object." }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp at which the row was inserted." }, "version": { "type": "integer", "minimum": 0, "description": "Dataset version this row belongs to." } }, "required": [ "rowId", "datasetId", "input", "output", "expectedOutput", "metadata", "createdAt", "version" ] }, "InsertDatasetRowsResponse": { "type": "object", "properties": { "versionId": { "type": "string", "description": "New dataset version id." }, "version": { "type": "integer", "minimum": 0, "description": "New dataset version number." }, "rowIds": { "type": "array", "items": { "type": "string" }, "description": "Ids of the inserted rows." } }, "required": [ "versionId", "version", "rowIds" ] }, "InsertDatasetRowsBody": { "type": "object", "properties": { "rows": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Optional client-supplied row id. Generated when omitted." }, "input": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": {} }, { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Row input cell." }, "output": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": {} }, { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Row output cell." }, "expectedOutput": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": {} }, { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Correct answer for this row. Filled in by curators; usually distinct from `output`." }, "metadata": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": {} }, { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Row metadata cell." } }, "required": [ "input" ] }, "minItems": 1, "description": "Rows to insert." } }, "required": [ "rows" ] }, "DeleteDatasetRowsResponse": { "type": "object", "properties": { "versionId": { "type": [ "string", "null" ], "description": "New dataset version id, or `null` when nothing was deleted." }, "version": { "type": "integer", "minimum": 0, "description": "New dataset version number." }, "deletedCount": { "type": "integer", "minimum": 0, "description": "Number of rows removed." } }, "required": [ "versionId", "version" ] }, "DeleteDatasetRowsBody": { "type": "object", "properties": { "selection": { "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "selected" ] }, "rowIds": { "type": "array", "items": { "type": "string" }, "minItems": 1 } }, "required": [ "mode", "rowIds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "all" ] } }, "required": [ "mode" ] }, { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "allExcept" ] }, "rowIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "mode", "rowIds" ] } ], "description": "Rows to delete." } }, "required": [ "selection" ] }, "ImportRowsFromTracesResponse": { "type": "object", "properties": { "versionId": { "type": "string", "description": "New dataset version id." }, "version": { "type": "integer", "minimum": 0, "description": "New dataset version number." }, "rowIds": { "type": "array", "items": { "type": "string" }, "description": "Ids of the inserted rows." } }, "required": [ "versionId", "version", "rowIds" ] }, "ImportRowsFromTracesBody": { "type": "object", "properties": { "traces": { "allOf": [ { "$ref": "#/components/schemas/TracesRef" }, { "description": "Which traces to import as rows — either explicit ids or a filter set." } ] } }, "required": [ "traces" ] }, "ExportDatasetRowsReadyResponse": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ready" ], "description": "Always `\"ready\"`. The CSV is available at `downloadUrl`." }, "downloadUrl": { "type": "string", "description": "Short-lived signed URL pointing to the CSV in object storage. Follow it with a plain HTTP GET." }, "filename": { "type": "string", "description": "Suggested filename for the downloaded CSV." }, "expiresAt": { "type": "string", "description": "ISO-8601 timestamp at which `downloadUrl` stops working." }, "rowCount": { "type": "integer", "minimum": 0, "description": "Number of rows included in the export." } }, "required": [ "status", "downloadUrl", "filename", "expiresAt", "rowCount" ] }, "ExportDatasetRowsQueuedResponse": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "queued" ], "description": "Always `\"queued\"`. The CSV is emailed to `recipient` when ready." }, "recipient": { "type": "string", "format": "email", "description": "Email address the export download link will be sent to." }, "rowCount": { "type": "integer", "minimum": 0, "description": "Number of rows the export will produce." } }, "required": [ "status", "recipient", "rowCount" ] }, "ExportDatasetRowsTooLargeResponse": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "too_large" ], "description": "Always `\"too_large\"`. The export exceeds the synchronous threshold." }, "rowCount": { "type": "integer", "minimum": 0, "description": "Number of rows the export would have produced." }, "threshold": { "type": "integer", "exclusiveMinimum": 0, "description": "Maximum row count this endpoint will generate synchronously." }, "recommendedAction": { "type": "string", "description": "Instructions for the caller — typically an LLM — on how to recover: ask the end user for an email address and retry the same call with `recipient` set to it." } }, "required": [ "status", "rowCount", "threshold", "recommendedAction" ] }, "ExportDatasetRowsBody": { "type": "object", "properties": { "selection": { "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "selected" ] }, "rowIds": { "type": "array", "items": { "type": "string" }, "minItems": 1 } }, "required": [ "mode", "rowIds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "all" ] } }, "required": [ "mode" ] }, { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "allExcept" ] }, "rowIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "mode", "rowIds" ] } ], "description": "Rows to export. Defaults to `{ mode: \"all\" }` when omitted." }, "recipient": { "type": "string", "format": "email", "description": "Email address to send the download link to when the export is too large for the synchronous path. Must belong to a member of the requesting organization. Ignored when the export fits the synchronous path; required for the async email flow." } } }, "ApiKey": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable API-key identifier." }, "organizationId": { "type": "string", "description": "Organization that owns this API key." }, "name": { "type": "string", "description": "Human-readable name." }, "token": { "type": "string", "description": "The full API key token. Returned by create / get / update — store it securely; treat it as a password." }, "lastUsedAt": { "type": [ "string", "null" ], "description": "ISO-8601 timestamp of the most recent successful authentication. `null` until first use." }, "deletedAt": { "type": [ "string", "null" ], "description": "ISO-8601 timestamp at which the key was revoked. `null` while the key is active." }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp of creation." }, "updatedAt": { "type": "string", "description": "ISO-8601 timestamp of the last metadata update (rename, revoke, last-used touch)." } }, "required": [ "id", "organizationId", "name", "token", "lastUsedAt", "deletedAt", "createdAt", "updatedAt" ] }, "CreateApiKeyBody": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Human-readable name for the API key. Used to distinguish keys in the UI." } }, "required": [ "name" ] }, "ApiKeyList": { "type": "object", "properties": { "apiKeys": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKeyListItem" } } }, "required": [ "apiKeys" ] }, "ApiKeyListItem": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable API-key identifier." }, "organizationId": { "type": "string", "description": "Organization that owns this API key." }, "name": { "type": "string", "description": "Human-readable name." }, "token": { "type": "string", "description": "Masked token preview safe to display in lists. Use `GET /api-keys/{apiKeyId}` to retrieve the full token." }, "lastUsedAt": { "type": [ "string", "null" ], "description": "ISO-8601 timestamp of the most recent successful authentication. `null` until first use." }, "deletedAt": { "type": [ "string", "null" ], "description": "ISO-8601 timestamp at which the key was revoked. `null` while the key is active." }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp of creation." }, "updatedAt": { "type": "string", "description": "ISO-8601 timestamp of the last metadata update." } }, "required": [ "id", "organizationId", "name", "token", "lastUsedAt", "deletedAt", "createdAt", "updatedAt" ] }, "UpdateApiKeyBody": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "New human-readable name for the API key." } }, "required": [ "name" ] }, "OAuthKeyList": { "type": "object", "properties": { "oauthKeys": { "type": "array", "items": { "$ref": "#/components/schemas/OAuthKey" } } }, "required": [ "oauthKeys" ] }, "OAuthKey": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable OAuth key identifier." }, "clientId": { "type": "string", "description": "Identifier of the OAuth client the key was issued to." }, "clientName": { "type": [ "string", "null" ], "description": "Display name of the OAuth client." }, "clientIcon": { "type": [ "string", "null" ], "description": "Icon URL of the OAuth client." }, "userId": { "type": "string", "description": "Identifier of the user the key belongs to." }, "userName": { "type": [ "string", "null" ], "description": "Display name of the user. `null` until the user completes onboarding." }, "userEmail": { "type": "string", "description": "Email of the user." }, "lastActivityAt": { "type": [ "string", "null" ], "description": "ISO-8601 timestamp of the last refresh on the key. `null` if the key has never been used." }, "connectedAt": { "type": "string", "description": "ISO-8601 timestamp at which the key was connected." }, "disabled": { "type": "boolean", "description": "Whether the key has been disabled." } }, "required": [ "id", "clientId", "clientName", "clientIcon", "userId", "userName", "userEmail", "lastActivityAt", "connectedAt", "disabled" ] }, "AccountResponse": { "type": "object", "properties": { "user": { "$ref": "#/components/schemas/AccountUser" }, "organization": { "$ref": "#/components/schemas/AccountOrganization" }, "role": { "type": [ "string", "null" ], "enum": [ "owner", "admin", "member", null ], "description": "Caller's role in the organization. `null` for API-key callers (no real user behind the credential)." } }, "required": [ "user", "organization", "role" ] }, "AccountUser": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "description": "Stable user identifier across the API." }, "email": { "type": "string", "description": "Verified email address of the authenticated user." }, "name": { "type": [ "string", "null" ], "description": "Display name, when set. `null` until the user completes onboarding." }, "image": { "type": [ "string", "null" ], "description": "Profile image URL, when set." } }, "required": [ "id", "email", "name", "image" ], "description": "The user the request is acting on behalf of. `null` for API-key callers — API keys are org-scoped, not user-scoped." }, "AccountOrganization": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable organization identifier across the API." }, "name": { "type": "string", "description": "Human-readable organization name." }, "slug": { "type": "string", "description": "URL-safe slug. Regenerated when the organization is renamed — don't use it as a stable key." } }, "required": [ "id", "name", "slug" ], "description": "Organization the request is scoped to." }, "MemberList": { "type": "object", "properties": { "members": { "type": "array", "items": { "$ref": "#/components/schemas/Member" } } }, "required": [ "members" ] }, "Member": { "oneOf": [ { "$ref": "#/components/schemas/ActiveMember" }, { "$ref": "#/components/schemas/InvitedMember" } ], "discriminator": { "propertyName": "status", "mapping": { "active": "#/components/schemas/ActiveMember", "invited": "#/components/schemas/InvitedMember" } } }, "ActiveMember": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "active" ], "description": "Discriminator for confirmed members — the user has accepted their invitation and joined the org." }, "id": { "type": "string", "description": "Stable membership identifier. Use this to address the row in update/remove endpoints." }, "organizationId": { "type": "string", "description": "Organization this membership belongs to." }, "userId": { "type": "string", "description": "Identifier of the user the membership represents." }, "role": { "type": "string", "enum": [ "owner", "admin", "member" ], "description": "Member's role within the organization." }, "name": { "type": [ "string", "null" ], "description": "Display name of the user. `null` if the user hasn't completed onboarding." }, "email": { "type": "string", "description": "User's email address, verified at signup." }, "image": { "type": [ "string", "null" ], "description": "User's profile image URL, when set." }, "joinedAt": { "type": "string", "description": "ISO-8601 timestamp at which the user joined the organization." } }, "required": [ "status", "id", "organizationId", "userId", "role", "name", "email", "image", "joinedAt" ] }, "InvitedMember": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "invited" ], "description": "Discriminator for pending invitations — the invitee hasn't accepted yet, so no user record exists." }, "id": { "type": "string", "description": "Stable invitation identifier. Distinct from membership ids." }, "organizationId": { "type": "string", "description": "Organization the invitation grants access to." }, "userId": { "type": "null", "description": "Always `null` — no user record exists until the invitation is accepted." }, "role": { "type": [ "string", "null" ], "enum": [ "owner", "admin", "member", null ], "description": "Role the invitee will get once they accept. `null` means the default (`member`)." }, "name": { "type": "null", "description": "Always `null` — no user record exists yet." }, "email": { "type": "string", "description": "Email address the invitation was sent to." }, "image": { "type": "null", "description": "Always `null` — no user record exists yet." }, "invitedAt": { "type": "string", "description": "ISO-8601 timestamp at which the invitation was created." }, "expiresAt": { "type": "string", "description": "ISO-8601 timestamp at which the invitation expires." }, "inviterId": { "type": "string", "description": "User id of the member who issued the invitation." } }, "required": [ "status", "id", "organizationId", "userId", "role", "name", "email", "image", "invitedAt", "expiresAt", "inviterId" ] }, "InviteMemberBody": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "Email address to invite. The invitee receives an accept link by email." }, "role": { "type": "string", "enum": [ "owner", "admin", "member" ], "description": "Role to grant on acceptance. Defaults to `member` when omitted." } }, "required": [ "email" ] }, "UpdateMemberRoleBody": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "admin", "member" ], "description": "New role. Owners cannot be changed via this endpoint — owner-transfer happens on the web." } }, "required": [ "role" ] }, "PaginatedMonitors": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Monitor" }, "description": "Page of items, in the requested sort order." }, "nextCursor": { "type": [ "string", "null" ], "description": "Opaque cursor for fetching the next page. `null` when there are no more pages. Pass it back in `cursor` to continue." }, "hasMore": { "type": "boolean", "description": "`true` when there is at least one more page after this one." } }, "required": [ "items", "nextCursor", "hasMore" ] }, "Monitor": { "type": "object", "properties": { "id": { "type": "string", "minLength": 24, "maxLength": 24, "description": "Stable monitor identifier." }, "organizationId": { "type": "string", "minLength": 24, "maxLength": 24, "description": "Organization that owns this monitor." }, "projectId": { "type": "string", "minLength": 24, "maxLength": 24, "description": "Project this monitor belongs to." }, "slug": { "type": "string", "description": "URL-safe slug derived from `name`. Unique within the project." }, "name": { "type": "string", "description": "Human-readable name." }, "description": { "type": "string", "description": "Free-form description. Empty string when not set." }, "system": { "type": "boolean", "description": "`true` for the auto-provisioned system monitors, which can't be deleted or edited; `false` otherwise." }, "alerts": { "type": "array", "items": { "$ref": "#/components/schemas/MonitorAlert" }, "description": "The monitor's alerts. Always at least one." }, "target": { "$ref": "#/components/schemas/MonitorTarget" }, "mutedAt": { "type": [ "string", "null" ], "description": "ISO-8601 timestamp at which the monitor was muted, or `null` when active." }, "deletedAt": { "type": [ "string", "null" ], "description": "ISO-8601 timestamp at which the monitor was deleted, or `null`." }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp of creation." }, "updatedAt": { "type": "string", "description": "ISO-8601 timestamp of the last update." } }, "required": [ "id", "organizationId", "projectId", "slug", "name", "description", "system", "alerts", "target", "mutedAt", "deletedAt", "createdAt", "updatedAt" ] }, "MonitorAlert": { "type": "object", "properties": { "id": { "type": "string", "minLength": 24, "maxLength": 24, "description": "Stable alert identifier." }, "monitorId": { "type": "string", "minLength": 24, "maxLength": 24, "description": "Monitor that owns this alert." }, "kind": { "type": "string", "enum": [ "issue.new", "issue.regressed", "issue.escalating", "savedSearch.match", "savedSearch.threshold", "savedSearch.escalating", "event.matched", "metric.threshold", "metric.escalating" ], "description": "What the alert fires on. The `savedSearch.*` kinds watch a saved search; `issue.*` are system-only." }, "source": { "$ref": "#/components/schemas/MonitorAlertSource" }, "condition": { "allOf": [ { "$ref": "#/components/schemas/AlertCondition" }, { "description": "Kind-specific configuration, or `null` for kinds with no parameters." } ] }, "severity": { "type": "string", "enum": [ "low", "medium", "high" ], "description": "Severity of incidents this alert opens: `low`, `medium`, or `high`." }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp of creation." } }, "required": [ "id", "monitorId", "kind", "source", "condition", "severity", "createdAt" ] }, "MonitorAlertSource": { "type": [ "object", "null" ], "properties": { "type": { "type": "string", "enum": [ "issue", "savedSearch" ], "description": "Entity the alert watches: `savedSearch` or `issue`." }, "id": { "type": [ "string", "null" ], "minLength": 24, "maxLength": 24, "description": "Id of the watched entity, or `null` to watch all entities of its `type`." } }, "required": [ "type", "id" ], "description": "The entity this alert watches, or `null` for unified alerts whose target lives on the monitor." }, "MonitorTarget": { "type": [ "object", "null" ], "properties": { "stream": { "type": "string", "enum": [ "traces", "spans", "sessions" ], "description": "Telemetry stream to evaluate: `traces` for users, `spans` for tools, or `sessions` for session-level monitors." }, "filterSet": { "$ref": "#/components/schemas/MonitorFilterSet" }, "query": { "type": [ "string", "null" ], "description": "Optional semantic query applied with the filters. Use `null` for user/tool monitors." }, "savedSearchId": { "type": [ "string", "null" ], "minLength": 24, "maxLength": 24, "description": "Saved-search target id, or `null` when `filterSet` and `query` define the target inline." }, "metric": { "allOf": [ { "$ref": "#/components/schemas/MonitorMetric" }, { "description": "Default metric measured by this monitor target." } ] } }, "required": [ "stream", "filterSet", "query", "savedSearchId", "metric" ], "description": "Unified query-time target for tool, user, and raw-stream monitors; `null` for legacy saved-search and system monitors." }, "MonitorFilterSet": { "type": [ "object", "null" ], "additionalProperties": { "type": "array", "items": { "$ref": "#/components/schemas/FilterCondition" } }, "description": "Filters that select the target rows. Use `{}` for all users; use `operation = execute_tool` for all tools." }, "CreateMonitorBody": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Human-readable name. Used to derive the slug." }, "description": { "type": "string", "maxLength": 2000, "description": "Optional free-form description." }, "alerts": { "type": "array", "items": { "$ref": "#/components/schemas/CreateMonitorAlertBody" }, "description": "The monitor's alert. Exactly one." }, "target": { "allOf": [ { "$ref": "#/components/schemas/MonitorTarget" }, { "description": "Target for tool/user monitors. Required for `event.*` and `metric.*` alerts; omit for saved-search alerts." } ] } }, "required": [ "name", "alerts" ] }, "CreateMonitorAlertBody": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "savedSearch.match", "savedSearch.threshold", "savedSearch.escalating", "event.matched", "metric.threshold", "metric.escalating" ], "description": "What the alert fires on. `savedSearch.*` kinds require a saved-search `source`; `event.*` and `metric.*` kinds require `source: null` and a monitor `target`." }, "source": { "allOf": [ { "$ref": "#/components/schemas/MonitorAlertSource" }, { "description": "Saved-search source for `savedSearch.*` alerts, or `null` for tool/user alerts whose target lives on the monitor." } ] }, "condition": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "savedSearch.threshold" ], "description": "Threshold alert: opens once the count threshold is crossed." }, "threshold": { "$ref": "#/components/schemas/AlertCountThreshold" } }, "required": [ "kind", "threshold" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "savedSearch.escalating" ], "description": "Sustained alert: opens only when the threshold stays crossed for the whole `window`." }, "threshold": { "$ref": "#/components/schemas/AlertCountThreshold" }, "window": { "type": "object", "properties": { "minutes": { "type": "integer", "minimum": 5, "description": "How long the threshold must stay crossed before the incident opens. The incident stays open while the threshold keeps holding over this window and closes once it no longer does. Minimum 5." } }, "required": [ "minutes" ], "description": "Sustained-condition window." } }, "required": [ "kind", "threshold", "window" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "issue.escalating" ], "description": "System signal-escalation alert; only `sensitivity` is tunable." }, "sensitivity": { "type": "integer", "minimum": 1, "maximum": 6, "description": "Detector sensitivity from 1 (noisiest) to 6 (strictest). Defaults to 3 when omitted." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "metric.threshold" ], "description": "Metric alert: opens once the target metric crosses a threshold." }, "metric": { "$ref": "#/components/schemas/MonitorMetric" }, "threshold": { "$ref": "#/components/schemas/AlertMetricThreshold" }, "direction": { "type": "string", "enum": [ "above", "below" ], "description": "Direction that opens the incident. Defaults to `above` when omitted." } }, "required": [ "kind", "metric", "threshold" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "metric.escalating" ], "description": "Sustained metric alert: opens when the target metric stays across threshold for the whole `window`." }, "metric": { "$ref": "#/components/schemas/MonitorMetric" }, "threshold": { "$ref": "#/components/schemas/AlertMetricThreshold" }, "direction": { "type": "string", "enum": [ "above", "below" ], "description": "Direction that opens the incident. Defaults to `above` when omitted." }, "window": { "type": "object", "properties": { "minutes": { "type": "integer", "minimum": 5, "description": "How long the threshold must stay crossed before the incident opens. Minimum 5." } }, "required": [ "minutes" ], "description": "Sustained-condition window." } }, "required": [ "kind", "metric", "threshold", "window" ] }, { "type": "null" } ], "description": "Kind-specific configuration. Required for threshold and escalating kinds; omit for match kinds." }, "severity": { "type": "string", "enum": [ "low", "medium", "high" ], "description": "Severity of incidents this alert opens. Defaults per kind when omitted." } }, "required": [ "kind", "source" ] }, "MonitorList": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Monitor" }, "description": "Matching monitors." } }, "required": [ "items" ] }, "ListMonitorsForTargetBody": { "type": "object", "properties": { "stream": { "type": "string", "enum": [ "traces", "spans", "sessions" ], "description": "Telemetry stream to evaluate: `traces` for users, `spans` for tools, or `sessions` for session-level monitors." }, "filterSetContains": { "allOf": [ { "$ref": "#/components/schemas/MonitorFilterSet" }, { "description": "Filter subset to match against monitor targets. For one user use `userId`; for one tool use `operation = execute_tool` and `toolName`." } ] } }, "required": [ "stream", "filterSetContains" ] }, "UpdateMonitorBody": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 128, "description": "New name. Renaming may regenerate the slug — re-read the response or rely on `id`." }, "description": { "type": "string", "maxLength": 2000, "description": "New description." } } }, "MonitorAlertList": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/MonitorAlert" }, "description": "The monitor's alerts." } }, "required": [ "items" ] }, "UpdateMonitorAlertBody": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "savedSearch.match", "savedSearch.threshold", "savedSearch.escalating", "event.matched", "metric.threshold", "metric.escalating" ], "description": "New alert kind. Not allowed on system monitors. Supply the matching `source` and `condition` when you change it." }, "source": { "type": [ "object", "null" ], "properties": { "type": { "type": "string", "enum": [ "issue", "savedSearch" ], "description": "Entity the alert watches: `savedSearch` or `issue`." }, "id": { "type": [ "string", "null" ], "minLength": 24, "maxLength": 24, "description": "Id of the watched entity, or `null` to watch all entities of its `type`." } }, "required": [ "type", "id" ], "description": "Replace the saved-search source, or set `null` for unified tool/user alerts. Not allowed on system monitors." }, "condition": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "savedSearch.threshold" ], "description": "Threshold alert: opens once the count threshold is crossed." }, "threshold": { "$ref": "#/components/schemas/AlertCountThreshold" } }, "required": [ "kind", "threshold" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "savedSearch.escalating" ], "description": "Sustained alert: opens only when the threshold stays crossed for the whole `window`." }, "threshold": { "$ref": "#/components/schemas/AlertCountThreshold" }, "window": { "type": "object", "properties": { "minutes": { "type": "integer", "minimum": 5, "description": "How long the threshold must stay crossed before the incident opens. The incident stays open while the threshold keeps holding over this window and closes once it no longer does. Minimum 5." } }, "required": [ "minutes" ], "description": "Sustained-condition window." } }, "required": [ "kind", "threshold", "window" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "issue.escalating" ], "description": "System signal-escalation alert; only `sensitivity` is tunable." }, "sensitivity": { "type": "integer", "minimum": 1, "maximum": 6, "description": "Detector sensitivity from 1 (noisiest) to 6 (strictest). Defaults to 3 when omitted." } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "metric.threshold" ], "description": "Metric alert: opens once the target metric crosses a threshold." }, "metric": { "$ref": "#/components/schemas/MonitorMetric" }, "threshold": { "$ref": "#/components/schemas/AlertMetricThreshold" }, "direction": { "type": "string", "enum": [ "above", "below" ], "description": "Direction that opens the incident. Defaults to `above` when omitted." } }, "required": [ "kind", "metric", "threshold" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "metric.escalating" ], "description": "Sustained metric alert: opens when the target metric stays across threshold for the whole `window`." }, "metric": { "$ref": "#/components/schemas/MonitorMetric" }, "threshold": { "$ref": "#/components/schemas/AlertMetricThreshold" }, "direction": { "type": "string", "enum": [ "above", "below" ], "description": "Direction that opens the incident. Defaults to `above` when omitted." }, "window": { "type": "object", "properties": { "minutes": { "type": "integer", "minimum": 5, "description": "How long the threshold must stay crossed before the incident opens. Minimum 5." } }, "required": [ "minutes" ], "description": "Sustained-condition window." } }, "required": [ "kind", "metric", "threshold", "window" ] }, { "type": "null" } ], "description": "Replace the alert's configuration. On system monitors this is the only editable field (e.g. signal-escalation `sensitivity`)." }, "severity": { "type": "string", "enum": [ "low", "medium", "high" ], "description": "Replace the severity. Not allowed on system monitors." } } }, "PaginatedMonitorIncidents": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/MonitorIncident" }, "description": "Page of items, in the requested sort order." }, "nextCursor": { "type": [ "string", "null" ], "description": "Opaque cursor for fetching the next page. `null` when there are no more pages. Pass it back in `cursor` to continue." }, "hasMore": { "type": "boolean", "description": "`true` when there is at least one more page after this one." } }, "required": [ "items", "nextCursor", "hasMore" ] }, "MonitorIncident": { "type": "object", "properties": { "id": { "type": "string", "minLength": 24, "maxLength": 24, "description": "Stable incident identifier." }, "organizationId": { "type": "string", "minLength": 24, "maxLength": 24, "description": "Organization that owns this incident." }, "projectId": { "type": "string", "minLength": 24, "maxLength": 24, "description": "Project this incident belongs to." }, "sourceType": { "type": "string", "enum": [ "issue", "savedSearch" ], "description": "Kind of entity that triggered the incident. `issue` for signal-lifecycle incidents; `savedSearch` for incidents raised by a monitor watching a search." }, "sourceId": { "type": "string", "minLength": 24, "maxLength": 24, "description": "Id of the entity that triggered the incident (matches `sourceType`)." }, "kind": { "type": "string", "enum": [ "issue.new", "issue.regressed", "issue.escalating", "savedSearch.match", "savedSearch.threshold", "savedSearch.escalating", "event.matched", "metric.threshold", "metric.escalating" ], "description": "Reason the incident opened. `issue.new` fires when a new signal is discovered; `issue.regressed` when a resolved signal is detected again; `issue.escalating` when an ongoing signal is being detected more than expected. The `savedSearch.*` kinds are raised by monitors watching a search: `savedSearch.match` on each new matching trace, `savedSearch.threshold` when matching traces are detected above a configured threshold, and `savedSearch.escalating` when they stay above the threshold for a sustained window." }, "severity": { "type": "string", "enum": [ "low", "medium", "high" ], "description": "Severity bucket assigned to the incident: `low`, `medium`, or `high`." }, "startedAt": { "type": "string", "description": "ISO-8601 timestamp at which the incident opened." }, "endedAt": { "type": [ "string", "null" ], "description": "ISO-8601 timestamp at which the incident closed, or `null` if still open." }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp at which the incident row was created." }, "monitorAlertId": { "type": [ "string", "null" ], "minLength": 24, "maxLength": 24, "description": "Id of the monitor alert that opened this incident, or `null` when not attributed to a monitor." }, "condition": { "$ref": "#/components/schemas/AlertCondition" }, "notified": { "type": "boolean", "description": "`true` when this incident triggered at least one notification." } }, "required": [ "id", "organizationId", "projectId", "sourceType", "sourceId", "kind", "severity", "startedAt", "endedAt", "createdAt", "monitorAlertId", "condition", "notified" ] } }, "parameters": {} }, "paths": { "/health": { "get": { "operationId": "health.get", "tags": [ "Health" ], "summary": "Health check", "x-fern-ignore": true, "responses": { "200": { "description": "Service is healthy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponse" } } } } } } }, "/.well-known/oauth-protected-resource": { "get": { "operationId": "wellKnown.oauthProtectedResource", "tags": [ "Well-known" ], "summary": "OAuth protected resource metadata", "description": "RFC 9728 metadata document advertising the authorization server(s) trusted to issue access tokens for this API.", "x-fern-ignore": true, "responses": { "200": { "description": "Protected resource metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthProtectedResourceMetadata" } } } } } } }, "/v1/projects": { "post": { "tags": [ "Projects" ], "x-fern-sdk-group-name": "projects", "x-fern-sdk-method-name": "create", "summary": "Create project", "description": "Creates a new project within the organization. The name must be unique within the org.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "createProject", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateProjectBody" } } } }, "responses": { "201": { "description": "Project created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "tags": [ "Projects" ], "x-fern-sdk-group-name": "projects", "x-fern-sdk-method-name": "list", "summary": "List projects", "description": "Returns every project in the organization. The response uses the standard paginated shape; the project list currently fits in a single page (`nextCursor` is always `null`).", "security": [ { "ApiKeyAuth": [] } ], "operationId": "listProjects", "responses": { "200": { "description": "List of projects", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedProjects" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}": { "get": { "tags": [ "Projects" ], "x-fern-sdk-group-name": "projects", "x-fern-sdk-method-name": "get", "summary": "Get project", "description": "Returns a single project by slug.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "getProject", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" } ], "responses": { "200": { "description": "Project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "tags": [ "Projects" ], "x-fern-sdk-group-name": "projects", "x-fern-sdk-method-name": "update", "summary": "Update project", "description": "Updates a project's name and/or settings. Renaming never changes the slug, and the slug cannot be changed via the API (only from the dashboard). Use `id` or `slug` as stable references.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "updateProject", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateProjectBody" } } } }, "responses": { "200": { "description": "Updated project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Projects" ], "x-fern-sdk-group-name": "projects", "x-fern-sdk-method-name": "delete", "summary": "Delete project", "description": "Deletes a project by slug.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "deleteProject", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" } ], "responses": { "204": { "description": "Project deleted" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/scores": { "post": { "tags": [ "Scores" ], "x-fern-sdk-group-name": "scores", "x-fern-sdk-method-name": "create", "summary": "Create project score", "description": "Creates a score against a target trace. The trace is resolved by explicit id (`trace.by = \"id\"`) or by a filter set (`trace.by = \"filters\"`, exactly one match required). Annotations use the separate `/annotations` endpoint.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "createScore", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateScoreBody" } } } }, "responses": { "201": { "description": "Score created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScoreResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/annotations": { "post": { "tags": [ "Annotations" ], "x-fern-sdk-group-name": "annotations", "x-fern-sdk-method-name": "create", "summary": "Create project annotation", "description": "Creates a published annotation score against a target trace. The trace is resolved by explicit id (`trace.by = \"id\"`) or by a filter set (`trace.by = \"filters\"`, exactly one match required). When called with an OAuth token, the annotation is attributed to the authenticated user.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "createAnnotation", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAnnotationBody" } } } }, "responses": { "201": { "description": "Annotation created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Annotation" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/traces/list": { "post": { "tags": [ "Traces" ], "x-fern-sdk-group-name": "traces", "x-fern-sdk-method-name": "list", "summary": "List project traces", "description": "Returns a cursor-paginated page of traces in the project. Combine `filters` with `query` (free-text semantic search) to narrow the result set. Trace list rows exclude per-message LLM content — use `getTrace` for the full conversation view.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "listTraces", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListTracesBody" } } } }, "responses": { "200": { "description": "Page of traces", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedTraces" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/traces/analytics": { "get": { "tags": [ "Traces" ], "x-fern-sdk-group-name": "traces", "x-fern-sdk-method-name": "analytics", "summary": "Get project trace analytics", "description": "Returns trace analytics for the project: a total (or median) per metric over the requested range, plus a per-bucket series for each metric. Buckets are 12-hour UTC-aligned. The range defaults to the trailing 7 days.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "getTraceAnalytics", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" }, { "schema": { "type": "string", "format": "date-time", "description": "Lower bound (inclusive) of the time range. Defaults to 7 days before `toIso`." }, "required": false, "description": "Lower bound (inclusive) of the time range. Defaults to 7 days before `toIso`.", "name": "fromIso", "in": "query" }, { "schema": { "type": "string", "format": "date-time", "description": "Upper bound (inclusive) of the time range. Defaults to now." }, "required": false, "description": "Upper bound (inclusive) of the time range. Defaults to now.", "name": "toIso", "in": "query" } ], "responses": { "200": { "description": "Trace analytics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TraceAnalyticsResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/traces/{traceId}": { "get": { "tags": [ "Traces" ], "x-fern-sdk-group-name": "traces", "x-fern-sdk-method-name": "get", "summary": "Get project trace", "description": "Returns a single trace by id, including the captured system instructions and the conversation messages from the trace's last LLM-completion span.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "getTrace", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" }, { "schema": { "type": "string", "minLength": 32, "maxLength": 32, "description": "32-character trace identifier." }, "required": true, "description": "32-character trace identifier.", "name": "traceId", "in": "path" } ], "responses": { "200": { "description": "Trace detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TraceDetail" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/traces/{traceId}/spans": { "get": { "tags": [ "Traces" ], "x-fern-sdk-group-name": "traces", "x-fern-sdk-method-name": "listSpans", "summary": "List trace spans", "description": "Returns every span belonging to the trace, ordered by `startTime` ascending. Spans carry the OpenTelemetry envelope (kind, status, attributes, resource) plus Latitude's GenAI enrichment (tokens, cost, operation, provider, model). Per-message LLM content is excluded for size; use a span point-lookup for the conversation payload.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "listTraceSpans", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" }, { "schema": { "type": "string", "minLength": 32, "maxLength": 32, "description": "32-character trace identifier." }, "required": true, "description": "32-character trace identifier.", "name": "traceId", "in": "path" } ], "responses": { "200": { "description": "Spans of the trace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TraceSpans" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/traces/{traceId}/spans/{spanId}": { "get": { "tags": [ "Traces" ], "x-fern-sdk-group-name": "traces", "x-fern-sdk-method-name": "getSpan", "summary": "Get trace span", "description": "Returns one span by id, including the LLM conversation (system instructions, input messages, output messages), tool data (definitions, call id, input, output), and the full OpenTelemetry payload (attributes, resource, events, links) that's excluded from the lighter list shape.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "getTraceSpan", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" }, { "schema": { "type": "string", "minLength": 32, "maxLength": 32, "description": "32-character trace identifier." }, "required": true, "description": "32-character trace identifier.", "name": "traceId", "in": "path" }, { "schema": { "type": "string", "minLength": 16, "maxLength": 16, "description": "16-character span identifier." }, "required": true, "description": "16-character span identifier.", "name": "spanId", "in": "path" } ], "responses": { "200": { "description": "Span detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpanDetail" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/traces/{traceId}/annotations": { "get": { "tags": [ "Traces" ], "x-fern-sdk-group-name": "traces", "x-fern-sdk-method-name": "listAnnotations", "summary": "List trace annotations", "description": "Returns a cursor-paginated page of annotations pinned to the trace, including both published annotations and drafts.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "listTraceAnnotations", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" }, { "schema": { "type": "string", "minLength": 32, "maxLength": 32, "description": "32-character trace identifier." }, "required": true, "description": "32-character trace identifier.", "name": "traceId", "in": "path" }, { "schema": { "type": "string", "description": "Opaque cursor returned in a previous response's `nextCursor`. Omit on the first page." }, "required": false, "description": "Opaque cursor returned in a previous response's `nextCursor`. Omit on the first page.", "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50, "description": "Page size. Defaults to 50; max 200." }, "required": false, "description": "Page size. Defaults to 50; max 200.", "name": "limit", "in": "query" } ], "responses": { "200": { "description": "Annotations of the trace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedTraceAnnotations" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/traces/{traceId}/annotations/{annotationId}": { "get": { "tags": [ "Traces" ], "x-fern-sdk-group-name": "traces", "x-fern-sdk-method-name": "getAnnotation", "summary": "Get trace annotation", "description": "Returns one annotation by id pinned to the trace.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "getTraceAnnotation", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" }, { "schema": { "type": "string", "minLength": 32, "maxLength": 32, "description": "32-character trace identifier." }, "required": true, "description": "32-character trace identifier.", "name": "traceId", "in": "path" }, { "schema": { "type": "string", "minLength": 24, "maxLength": 24, "description": "Stable annotation identifier." }, "required": true, "description": "Stable annotation identifier.", "name": "annotationId", "in": "path" } ], "responses": { "200": { "description": "Annotation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Annotation" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/traces/export": { "post": { "tags": [ "Traces" ], "x-fern-sdk-group-name": "traces", "x-fern-sdk-method-name": "export", "summary": "Export project traces (async)", "description": "Enqueues a CSV export of the traces matched by `traces`. The export runs asynchronously; a download link is emailed to `recipient` when the file is ready. The response returns immediately with `status = \"queued\"`. The recipient must already be a member of the requesting organization.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "exportTraces", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportTracesBody" } } } }, "responses": { "202": { "description": "Export enqueued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportTracesResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/tools": { "get": { "tags": [ "Tools" ], "x-fern-sdk-group-name": "tools", "x-fern-sdk-method-name": "list", "summary": "List project tools with usage metrics", "description": "Returns every tool in the project over the range — the union of defined and called tools — with per-tool usage metrics, offered counts, a call trend, and project-wide totals. The range defaults to the trailing 7 days.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "listTools", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" }, { "schema": { "type": "string", "format": "date-time", "description": "Lower bound (inclusive) of the time range. Defaults to 7 days before `toIso`." }, "required": false, "description": "Lower bound (inclusive) of the time range. Defaults to 7 days before `toIso`.", "name": "fromIso", "in": "query" }, { "schema": { "type": "string", "format": "date-time", "description": "Upper bound (inclusive) of the time range. Defaults to now." }, "required": false, "description": "Upper bound (inclusive) of the time range. Defaults to now.", "name": "toIso", "in": "query" }, { "schema": { "type": "integer", "minimum": 3600, "maximum": 7776000, "description": "Bucket width in seconds. Derived from the range (~30 buckets) when omitted." }, "required": false, "description": "Bucket width in seconds. Derived from the range (~30 buckets) when omitted.", "name": "trendBucketSeconds", "in": "query" } ], "responses": { "200": { "description": "Tools analytics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolsAnalyticsResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/tools/histogram": { "get": { "tags": [ "Tools" ], "x-fern-sdk-group-name": "tools", "x-fern-sdk-method-name": "histogram", "summary": "Get tool call histogram", "description": "Returns per-bucket call counts over the range. Omit `toolName` to aggregate across every tool in the project; pass it to scope the histogram to a single tool.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "getToolCallHistogram", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" }, { "schema": { "type": "string", "format": "date-time", "description": "Lower bound (inclusive) of the time range. Defaults to 7 days before `toIso`." }, "required": false, "description": "Lower bound (inclusive) of the time range. Defaults to 7 days before `toIso`.", "name": "fromIso", "in": "query" }, { "schema": { "type": "string", "format": "date-time", "description": "Upper bound (inclusive) of the time range. Defaults to now." }, "required": false, "description": "Upper bound (inclusive) of the time range. Defaults to now.", "name": "toIso", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Tool name. URL-encode names containing special characters." }, "required": false, "description": "Tool name. URL-encode names containing special characters.", "name": "toolName", "in": "query" }, { "schema": { "type": "integer", "minimum": 3600, "maximum": 7776000, "description": "Bucket width in seconds. Derived from the range (~30 buckets) when omitted." }, "required": false, "description": "Bucket width in seconds. Derived from the range (~30 buckets) when omitted.", "name": "bucketSeconds", "in": "query" }, { "schema": { "type": "string", "enum": [ "true", "false" ], "description": "When `true`, scope every aggregate to failed calls only." }, "required": false, "description": "When `true`, scope every aggregate to failed calls only.", "name": "errorsOnly", "in": "query" } ], "responses": { "200": { "description": "Call histogram", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolHistogramResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/tools/{toolName}/parameters": { "get": { "tags": [ "Tools" ], "x-fern-sdk-group-name": "tools", "x-fern-sdk-method-name": "parameters", "summary": "Get tool parameter stats", "description": "Returns the most common top-level input keys and their most common values for the tool, computed over a sample of the most recent calls in the range.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "getToolParameters", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Tool name. URL-encode names containing special characters." }, "required": true, "description": "Tool name. URL-encode names containing special characters.", "name": "toolName", "in": "path" }, { "schema": { "type": "string", "format": "date-time", "description": "Lower bound (inclusive) of the time range. Defaults to 7 days before `toIso`." }, "required": false, "description": "Lower bound (inclusive) of the time range. Defaults to 7 days before `toIso`.", "name": "fromIso", "in": "query" }, { "schema": { "type": "string", "format": "date-time", "description": "Upper bound (inclusive) of the time range. Defaults to now." }, "required": false, "description": "Upper bound (inclusive) of the time range. Defaults to now.", "name": "toIso", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 50, "description": "Maximum number of keys to return." }, "required": false, "description": "Maximum number of keys to return.", "name": "topKeys", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 10, "description": "Maximum number of values to return per key." }, "required": false, "description": "Maximum number of values to return per key.", "name": "topValuesPerKey", "in": "query" }, { "schema": { "type": "string", "enum": [ "true", "false" ], "description": "When `true`, scope every aggregate to failed calls only." }, "required": false, "description": "When `true`, scope every aggregate to failed calls only.", "name": "errorsOnly", "in": "query" } ], "responses": { "200": { "description": "Parameter stats", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolParameterStatsResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/tools/{toolName}/context": { "get": { "tags": [ "Tools" ], "x-fern-sdk-group-name": "tools", "x-fern-sdk-method-name": "context", "summary": "Get tool context breakdown", "description": "Returns where the tool is used, broken down by a dimension: `model` and `provider` attribute the tool's traces via their chat spans; `tag` reads tags on the tool-call spans themselves.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "getToolContext", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Tool name. URL-encode names containing special characters." }, "required": true, "description": "Tool name. URL-encode names containing special characters.", "name": "toolName", "in": "path" }, { "schema": { "type": "string", "format": "date-time", "description": "Lower bound (inclusive) of the time range. Defaults to 7 days before `toIso`." }, "required": false, "description": "Lower bound (inclusive) of the time range. Defaults to 7 days before `toIso`.", "name": "fromIso", "in": "query" }, { "schema": { "type": "string", "format": "date-time", "description": "Upper bound (inclusive) of the time range. Defaults to now." }, "required": false, "description": "Upper bound (inclusive) of the time range. Defaults to now.", "name": "toIso", "in": "query" }, { "schema": { "type": "string", "enum": [ "model", "provider", "tag" ], "description": "Dimension to break the usage down by." }, "required": true, "description": "Dimension to break the usage down by.", "name": "dimension", "in": "query" }, { "schema": { "type": "string", "enum": [ "true", "false" ], "description": "When `true`, scope every aggregate to failed calls only." }, "required": false, "description": "When `true`, scope every aggregate to failed calls only.", "name": "errorsOnly", "in": "query" } ], "responses": { "200": { "description": "Context breakdown", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolContextBreakdownResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/tools/{toolName}/co-occurrence": { "get": { "tags": [ "Tools" ], "x-fern-sdk-group-name": "tools", "x-fern-sdk-method-name": "coOccurrence", "summary": "Get co-occurring tools", "description": "Returns other tools called in the same traces as this one, ranked by shared trace count.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "getToolCoOccurrence", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Tool name. URL-encode names containing special characters." }, "required": true, "description": "Tool name. URL-encode names containing special characters.", "name": "toolName", "in": "path" }, { "schema": { "type": "string", "format": "date-time", "description": "Lower bound (inclusive) of the time range. Defaults to 7 days before `toIso`." }, "required": false, "description": "Lower bound (inclusive) of the time range. Defaults to 7 days before `toIso`.", "name": "fromIso", "in": "query" }, { "schema": { "type": "string", "format": "date-time", "description": "Upper bound (inclusive) of the time range. Defaults to now." }, "required": false, "description": "Upper bound (inclusive) of the time range. Defaults to now.", "name": "toIso", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 50, "description": "Maximum number of tools to return." }, "required": false, "description": "Maximum number of tools to return.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "enum": [ "true", "false" ], "description": "When `true`, scope every aggregate to failed calls only." }, "required": false, "description": "When `true`, scope every aggregate to failed calls only.", "name": "errorsOnly", "in": "query" } ], "responses": { "200": { "description": "Co-occurring tools", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCoOccurrenceResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/tools/{toolName}/errors": { "get": { "tags": [ "Tools" ], "x-fern-sdk-group-name": "tools", "x-fern-sdk-method-name": "errors", "summary": "Get tool error breakdown", "description": "Returns the most common error outputs of the tool's failed calls, grouped into clusters by a normalized form so variable fragments don't split one error into many buckets.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "getToolErrors", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Tool name. URL-encode names containing special characters." }, "required": true, "description": "Tool name. URL-encode names containing special characters.", "name": "toolName", "in": "path" }, { "schema": { "type": "string", "format": "date-time", "description": "Lower bound (inclusive) of the time range. Defaults to 7 days before `toIso`." }, "required": false, "description": "Lower bound (inclusive) of the time range. Defaults to 7 days before `toIso`.", "name": "fromIso", "in": "query" }, { "schema": { "type": "string", "format": "date-time", "description": "Upper bound (inclusive) of the time range. Defaults to now." }, "required": false, "description": "Upper bound (inclusive) of the time range. Defaults to now.", "name": "toIso", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 50, "description": "Maximum number of clusters to return." }, "required": false, "description": "Maximum number of clusters to return.", "name": "limit", "in": "query" } ], "responses": { "200": { "description": "Error breakdown", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolErrorBreakdownResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/tools/{toolName}/calls": { "get": { "tags": [ "Tools" ], "x-fern-sdk-group-name": "tools", "x-fern-sdk-method-name": "listCalls", "summary": "List recent tool calls", "description": "Returns a cursor-paginated page of the tool's most recent calls, newest first, with payloads truncated to a bounded preview. Use a span point-lookup for full payloads.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "listToolCalls", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Tool name. URL-encode names containing special characters." }, "required": true, "description": "Tool name. URL-encode names containing special characters.", "name": "toolName", "in": "path" }, { "schema": { "type": "string", "format": "date-time", "description": "Lower bound (inclusive) of the time range. Defaults to 7 days before `toIso`." }, "required": false, "description": "Lower bound (inclusive) of the time range. Defaults to 7 days before `toIso`.", "name": "fromIso", "in": "query" }, { "schema": { "type": "string", "format": "date-time", "description": "Upper bound (inclusive) of the time range. Defaults to now." }, "required": false, "description": "Upper bound (inclusive) of the time range. Defaults to now.", "name": "toIso", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 50, "description": "Page size. Defaults to 50; max 50." }, "required": false, "description": "Page size. Defaults to 50; max 50.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "enum": [ "true", "false" ], "description": "When `true`, scope every aggregate to failed calls only." }, "required": false, "description": "When `true`, scope every aggregate to failed calls only.", "name": "errorsOnly", "in": "query" }, { "schema": { "type": "string", "description": "Opaque cursor returned in a previous response's `nextCursor`. Omit on the first page." }, "required": false, "description": "Opaque cursor returned in a previous response's `nextCursor`. Omit on the first page.", "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "Page of tool calls", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedToolCalls" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/tools/{toolName}": { "get": { "tags": [ "Tools" ], "x-fern-sdk-group-name": "tools", "x-fern-sdk-method-name": "get", "summary": "Get tool detail", "description": "Returns the latest definition seen for the tool plus its global usage metrics. Pass `errorsOnly=true` to also include failed-calls-only metrics for failure analysis.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "getTool", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Tool name. URL-encode names containing special characters." }, "required": true, "description": "Tool name. URL-encode names containing special characters.", "name": "toolName", "in": "path" }, { "schema": { "type": "string", "format": "date-time", "description": "Lower bound (inclusive) of the time range. Defaults to 7 days before `toIso`." }, "required": false, "description": "Lower bound (inclusive) of the time range. Defaults to 7 days before `toIso`.", "name": "fromIso", "in": "query" }, { "schema": { "type": "string", "format": "date-time", "description": "Upper bound (inclusive) of the time range. Defaults to now." }, "required": false, "description": "Upper bound (inclusive) of the time range. Defaults to now.", "name": "toIso", "in": "query" }, { "schema": { "type": "string", "enum": [ "true", "false" ], "description": "When `true`, scope every aggregate to failed calls only." }, "required": false, "description": "When `true`, scope every aggregate to failed calls only.", "name": "errorsOnly", "in": "query" } ], "responses": { "200": { "description": "Tool detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolDetailResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/users": { "get": { "tags": [ "Users" ], "x-fern-sdk-group-name": "users", "x-fern-sdk-method-name": "list", "summary": "List project end-users with usage metrics", "description": "Returns a page of the project's identified end-users over the range, each with trace, session, token, and cost metrics, plus cost aggregates across every matching user. The range defaults to the trailing 30 days.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "listUsers", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" }, { "schema": { "type": "string", "format": "date-time", "description": "Lower bound (inclusive) of the time range. Defaults to 30 days before `toIso`." }, "required": false, "description": "Lower bound (inclusive) of the time range. Defaults to 30 days before `toIso`.", "name": "fromIso", "in": "query" }, { "schema": { "type": "string", "format": "date-time", "description": "Upper bound (inclusive) of the time range. Defaults to now." }, "required": false, "description": "Upper bound (inclusive) of the time range. Defaults to now.", "name": "toIso", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Page size. Max 100." }, "required": false, "description": "Page size. Max 100.", "name": "limit", "in": "query" }, { "schema": { "type": [ "integer", "null" ], "minimum": 0, "description": "Zero-based offset of the first user to return." }, "required": false, "description": "Zero-based offset of the first user to return.", "name": "offset", "in": "query" }, { "schema": { "type": "string", "enum": [ "lastSeen", "firstSeen", "traces", "sessions", "errors", "tokens", "cost", "costAvg", "costMedian" ], "description": "Field to sort by. Defaults to most recently seen." }, "required": false, "description": "Field to sort by. Defaults to most recently seen.", "name": "sortBy", "in": "query" }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort direction. Defaults to descending." }, "required": false, "description": "Sort direction. Defaults to descending.", "name": "sortDirection", "in": "query" }, { "schema": { "type": "string", "maxLength": 500, "description": "Case-insensitive substring match on the user's id or email." }, "required": false, "description": "Case-insensitive substring match on the user's id or email.", "name": "searchQuery", "in": "query" } ], "responses": { "200": { "description": "Page of end-users", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserListResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/users/overview": { "get": { "tags": [ "Users" ], "x-fern-sdk-group-name": "users", "x-fern-sdk-method-name": "overview", "summary": "Get project end-user overview", "description": "Returns project-wide end-user aggregates over the range — unique and new users, identified vs total traces and sessions — plus a per-bucket activity histogram. The range defaults to the trailing 30 days.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "getUsersOverview", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" }, { "schema": { "type": "string", "format": "date-time", "description": "Lower bound (inclusive) of the time range. Defaults to 30 days before `toIso`." }, "required": false, "description": "Lower bound (inclusive) of the time range. Defaults to 30 days before `toIso`.", "name": "fromIso", "in": "query" }, { "schema": { "type": "string", "format": "date-time", "description": "Upper bound (inclusive) of the time range. Defaults to now." }, "required": false, "description": "Upper bound (inclusive) of the time range. Defaults to now.", "name": "toIso", "in": "query" } ], "responses": { "200": { "description": "Users overview", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsersOverviewResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/users/{userId}/activity": { "get": { "tags": [ "Users" ], "x-fern-sdk-group-name": "users", "x-fern-sdk-method-name": "activity", "summary": "Get end-user activity histogram", "description": "Returns the end-user's per-bucket session activity across the range, oldest first. The range defaults to the trailing 30 days.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "getUserActivity", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "End-user identifier. URL-encode values containing special characters." }, "required": true, "description": "End-user identifier. URL-encode values containing special characters.", "name": "userId", "in": "path" }, { "schema": { "type": "string", "format": "date-time", "description": "Lower bound (inclusive) of the time range. Defaults to 30 days before `toIso`." }, "required": false, "description": "Lower bound (inclusive) of the time range. Defaults to 30 days before `toIso`.", "name": "fromIso", "in": "query" }, { "schema": { "type": "string", "format": "date-time", "description": "Upper bound (inclusive) of the time range. Defaults to now." }, "required": false, "description": "Upper bound (inclusive) of the time range. Defaults to now.", "name": "toIso", "in": "query" }, { "schema": { "type": "string", "enum": [ "true", "false" ], "description": "When `true`, scope every aggregate to errored traces only." }, "required": false, "description": "When `true`, scope every aggregate to errored traces only.", "name": "errorsOnly", "in": "query" } ], "responses": { "200": { "description": "Activity histogram", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserActivityResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/users/{userId}/usage": { "get": { "tags": [ "Users" ], "x-fern-sdk-group-name": "users", "x-fern-sdk-method-name": "usage", "summary": "Get end-user usage breakdown", "description": "Returns the end-user's top values of a usage dimension — `model`, `provider`, or `tool` — ranked by distinct trace count.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "getUserUsage", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "End-user identifier. URL-encode values containing special characters." }, "required": true, "description": "End-user identifier. URL-encode values containing special characters.", "name": "userId", "in": "path" }, { "schema": { "type": "string", "enum": [ "model", "provider", "tool" ], "description": "Dimension to break the usage down by." }, "required": true, "description": "Dimension to break the usage down by.", "name": "dimension", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 50, "description": "Maximum number of values to return." }, "required": false, "description": "Maximum number of values to return.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "enum": [ "true", "false" ], "description": "When `true`, scope every aggregate to errored traces only." }, "required": false, "description": "When `true`, scope every aggregate to errored traces only.", "name": "errorsOnly", "in": "query" } ], "responses": { "200": { "description": "Usage breakdown", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserUsageResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/users/{userId}/signals": { "get": { "tags": [ "Users" ], "x-fern-sdk-group-name": "users", "x-fern-sdk-method-name": "signals", "summary": "List signals on an end-user's traces", "description": "Returns the signals that occurred on the end-user's traces, most recent occurrence first. Occurrence counts are scoped to the user; signal identity and lifecycle states are the project's.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "listUserSignals", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "End-user identifier. URL-encode values containing special characters." }, "required": true, "description": "End-user identifier. URL-encode values containing special characters.", "name": "userId", "in": "path" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Maximum number of signals to return." }, "required": false, "description": "Maximum number of signals to return.", "name": "limit", "in": "query" } ], "responses": { "200": { "description": "User signals", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserSignalsResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/users/{userId}/behaviours": { "get": { "tags": [ "Users" ], "x-fern-sdk-group-name": "users", "x-fern-sdk-method-name": "behaviours", "summary": "List behaviours observed for an end-user", "description": "Returns the behaviour clusters observed on the end-user's sessions, most frequent first. Counts are scoped to the user; cluster identity comes from the project taxonomy.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "listUserBehaviours", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "End-user identifier. URL-encode values containing special characters." }, "required": true, "description": "End-user identifier. URL-encode values containing special characters.", "name": "userId", "in": "path" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Maximum number of behaviours to return." }, "required": false, "description": "Maximum number of behaviours to return.", "name": "limit", "in": "query" } ], "responses": { "200": { "description": "User behaviours", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserBehavioursResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/users/{userId}": { "get": { "tags": [ "Users" ], "x-fern-sdk-group-name": "users", "x-fern-sdk-method-name": "get", "summary": "Get end-user profile", "description": "Returns the lifetime profile of one end-user — trace, session, token, cost, and activity rollups across all of the user's traces (not range-bound).", "security": [ { "ApiKeyAuth": [] } ], "operationId": "getUser", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "End-user identifier. URL-encode values containing special characters." }, "required": true, "description": "End-user identifier. URL-encode values containing special characters.", "name": "userId", "in": "path" }, { "schema": { "type": "string", "enum": [ "true", "false" ], "description": "When `true`, scope every aggregate to errored traces only." }, "required": false, "description": "When `true`, scope every aggregate to errored traces only.", "name": "errorsOnly", "in": "query" } ], "responses": { "200": { "description": "User profile", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserProfileResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/searches": { "get": { "tags": [ "Saved Searches" ], "x-fern-sdk-group-name": "savedSearches", "x-fern-sdk-method-name": "list", "summary": "List saved searches", "description": "Returns every saved search in the project. The response uses the standard paginated shape; the saved-search list currently fits in a single page (`nextCursor` is always `null`).", "security": [ { "ApiKeyAuth": [] } ], "operationId": "listSavedSearches", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" } ], "responses": { "200": { "description": "List of saved searches", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedSavedSearches" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Saved Searches" ], "x-fern-sdk-group-name": "savedSearches", "x-fern-sdk-method-name": "create", "summary": "Create saved search", "description": "Creates a saved search within the project. At least one of `query` or `filters` must be set. The slug is derived from `name`. OAuth-authenticated only.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "createSavedSearch", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSavedSearchBody" } } } }, "responses": { "201": { "description": "Saved search created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedSearch" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/searches/{searchSlug}": { "get": { "tags": [ "Saved Searches" ], "x-fern-sdk-group-name": "savedSearches", "x-fern-sdk-method-name": "get", "summary": "Get saved search", "description": "Returns a single saved search by slug.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "getSavedSearch", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" }, { "schema": { "type": "string", "description": "Saved-search slug (human-readable identifier within the project)." }, "required": true, "description": "Saved-search slug (human-readable identifier within the project).", "name": "searchSlug", "in": "path" } ], "responses": { "200": { "description": "Saved search", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedSearch" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "tags": [ "Saved Searches" ], "x-fern-sdk-group-name": "savedSearches", "x-fern-sdk-method-name": "update", "summary": "Update saved search", "description": "Updates a saved search. Renaming may regenerate the slug — clients should re-read the response or rely on the `id` for stable references.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "updateSavedSearch", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" }, { "schema": { "type": "string", "description": "Saved-search slug (human-readable identifier within the project)." }, "required": true, "description": "Saved-search slug (human-readable identifier within the project).", "name": "searchSlug", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSavedSearchBody" } } } }, "responses": { "200": { "description": "Updated saved search", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedSearch" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Saved Searches" ], "x-fern-sdk-group-name": "savedSearches", "x-fern-sdk-method-name": "delete", "summary": "Delete saved search", "description": "Deletes a saved search by slug.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "deleteSavedSearch", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" }, { "schema": { "type": "string", "description": "Saved-search slug (human-readable identifier within the project)." }, "required": true, "description": "Saved-search slug (human-readable identifier within the project).", "name": "searchSlug", "in": "path" } ], "responses": { "204": { "description": "Saved search deleted" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/searches/{searchSlug}/traces": { "get": { "tags": [ "Saved Searches" ], "x-fern-sdk-group-name": "savedSearches", "x-fern-sdk-method-name": "listTraces", "summary": "List traces matching a saved search", "description": "Returns a cursor-paginated page of traces that match the saved search's `query` + `filters`. Each row uses the same `Trace` shape as `listTraces` — use the trace point-lookup endpoints (`getTrace`, `listTraceSpans`, `getTraceSpan`, `listTraceAnnotations`) to drill into individual traces.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "listSavedSearchTraces", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" }, { "schema": { "type": "string", "description": "Saved-search slug (human-readable identifier within the project)." }, "required": true, "description": "Saved-search slug (human-readable identifier within the project).", "name": "searchSlug", "in": "path" }, { "schema": { "type": "string", "description": "Opaque cursor returned in a previous response's `nextCursor`. Omit on the first page." }, "required": false, "description": "Opaque cursor returned in a previous response's `nextCursor`. Omit on the first page.", "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50, "description": "Page size. Defaults to 50; max 200." }, "required": false, "description": "Page size. Defaults to 50; max 200.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "enum": [ "relevance", "startTime", "endTime", "durationNs", "tokensTotal", "costTotalMicrocents" ], "default": "startTime", "description": "Field to sort by. Defaults to `startTime`. Pass `relevance` to rank by semantic match against the saved search's query (best match first, then most recent)." }, "required": false, "description": "Field to sort by. Defaults to `startTime`. Pass `relevance` to rank by semantic match against the saved search's query (best match first, then most recent).", "name": "sortBy", "in": "query" }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc", "description": "Sort direction. Defaults to `desc` (most recent first)." }, "required": false, "description": "Sort direction. Defaults to `desc` (most recent first).", "name": "sortDirection", "in": "query" } ], "responses": { "200": { "description": "Page of traces", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedTraces" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/signals": { "get": { "tags": [ "Signals" ], "x-fern-sdk-group-name": "signals", "x-fern-sdk-method-name": "list", "summary": "List project signals", "description": "Returns a cursor-paginated page of signals in the project. Each item includes lifecycle `states` plus time-window stats: `firstSeenAt`, `lastSeenAt`, `occurrences`, `affectedTracesPercent`, `trend`, and `tags`.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "listSignals", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" }, { "schema": { "type": "string", "description": "Opaque cursor returned in a previous response's `nextCursor`. Omit on the first page." }, "required": false, "description": "Opaque cursor returned in a previous response's `nextCursor`. Omit on the first page.", "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50, "description": "Page size. Defaults to 50; max 200." }, "required": false, "description": "Page size. Defaults to 50; max 200.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Free-text semantic search across the signals' names and descriptions." }, "required": false, "description": "Free-text semantic search across the signals' names and descriptions.", "name": "query", "in": "query" }, { "schema": { "type": "string", "enum": [ "active", "archived" ], "description": "`\"active\"` for unresolved/unignored signals; `\"archived\"` for the rest. Omit to include both." }, "required": false, "description": "`\"active\"` for unresolved/unignored signals; `\"archived\"` for the rest. Omit to include both.", "name": "lifecycleGroup", "in": "query" }, { "schema": { "type": "string", "enum": [ "lastSeen", "occurrences", "state" ], "default": "lastSeen", "description": "Sort field. `lastSeen` orders by most recent occurrence; `occurrences` by total count in the time window; `state` by lifecycle priority." }, "required": false, "description": "Sort field. `lastSeen` orders by most recent occurrence; `occurrences` by total count in the time window; `state` by lifecycle priority.", "name": "sortBy", "in": "query" }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc", "description": "Sort direction. Defaults to `desc`." }, "required": false, "description": "Sort direction. Defaults to `desc`.", "name": "sortDirection", "in": "query" }, { "schema": { "type": "string", "format": "date-time", "description": "Lower bound (inclusive) of the time window. Defaults to ~6 days ago." }, "required": false, "description": "Lower bound (inclusive) of the time window. Defaults to ~6 days ago.", "name": "fromIso", "in": "query" }, { "schema": { "type": "string", "format": "date-time", "description": "Upper bound (inclusive) of the time window. Defaults to now." }, "required": false, "description": "Upper bound (inclusive) of the time window. Defaults to now.", "name": "toIso", "in": "query" } ], "responses": { "200": { "description": "Page of signals", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedSignals" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/signals/analytics": { "get": { "tags": [ "Signals" ], "x-fern-sdk-group-name": "signals", "x-fern-sdk-method-name": "analytics", "summary": "Get project signal analytics", "description": "Returns signal analytics for the project: counts of ongoing, new, escalating, regressed, and resolved signals, plus total occurrences and a per-bucket occurrence series. Buckets are 12-hour UTC-aligned. The range defaults to the trailing 7 days.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "getSignalAnalytics", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" }, { "schema": { "type": "string", "format": "date-time", "description": "Lower bound (inclusive) of the time range. Defaults to 7 days before `toIso`." }, "required": false, "description": "Lower bound (inclusive) of the time range. Defaults to 7 days before `toIso`.", "name": "fromIso", "in": "query" }, { "schema": { "type": "string", "format": "date-time", "description": "Upper bound (inclusive) of the time range. Defaults to now." }, "required": false, "description": "Upper bound (inclusive) of the time range. Defaults to now.", "name": "toIso", "in": "query" } ], "responses": { "200": { "description": "Signal analytics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignalAnalyticsResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/signals/{signalSlug}": { "get": { "tags": [ "Signals" ], "x-fern-sdk-group-name": "signals", "x-fern-sdk-method-name": "get", "summary": "Get project signal", "description": "Returns the full-history detail view of one signal: lifecycle `states`, lifetime activity stats (`firstSeenAt`, `lastSeenAt`, `occurrences`, `affectedTracesPercent`, `tags`), a 14-day occurrence `trend`, the active `evaluations` monitoring it, and the current `monitoringState`.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "getSignal", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" }, { "schema": { "type": "string", "description": "Signal slug." }, "required": true, "description": "Signal slug.", "name": "signalSlug", "in": "path" } ], "responses": { "200": { "description": "Signal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignalDetail" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/signals/{signalSlug}/trend": { "get": { "tags": [ "Signals" ], "x-fern-sdk-group-name": "signals", "x-fern-sdk-method-name": "trend", "summary": "Get signal occurrence histogram", "description": "Returns the occurrence histogram for one signal over `[fromIso, toIso]`. The default range is the trailing 14 days. Buckets are 12-hour wide and UTC-aligned.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "getSignalTrend", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" }, { "schema": { "type": "string", "description": "Signal slug." }, "required": true, "description": "Signal slug.", "name": "signalSlug", "in": "path" }, { "schema": { "type": "string", "format": "date-time", "description": "Lower bound (inclusive). Defaults to ~14 days before `toIso`." }, "required": false, "description": "Lower bound (inclusive). Defaults to ~14 days before `toIso`.", "name": "fromIso", "in": "query" }, { "schema": { "type": "string", "format": "date-time", "description": "Upper bound (inclusive). Defaults to now." }, "required": false, "description": "Upper bound (inclusive). Defaults to now.", "name": "toIso", "in": "query" } ], "responses": { "200": { "description": "Occurrence histogram", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignalHistogram" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/signals/{signalSlug}/traces": { "get": { "tags": [ "Signals" ], "x-fern-sdk-group-name": "signals", "x-fern-sdk-method-name": "listTraces", "summary": "List signal traces", "description": "Returns the page of distinct traces that contributed at least one occurrence of the signal, ordered by most recent activity first.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "listSignalTraces", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" }, { "schema": { "type": "string", "description": "Signal slug." }, "required": true, "description": "Signal slug.", "name": "signalSlug", "in": "path" }, { "schema": { "type": "string", "description": "Opaque cursor returned in a previous response's `nextCursor`. Omit on the first page." }, "required": false, "description": "Opaque cursor returned in a previous response's `nextCursor`. Omit on the first page.", "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50, "description": "Page size. Defaults to 50; max 200." }, "required": false, "description": "Page size. Defaults to 50; max 200.", "name": "limit", "in": "query" } ], "responses": { "200": { "description": "Page of traces", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedTraces" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/signals/resolve": { "post": { "tags": [ "Signals" ], "x-fern-sdk-group-name": "signals", "x-fern-sdk-method-name": "resolve", "summary": "Resolve signals", "description": "Marks each signal in `signalIds` as resolved. When `keepMonitoring` is `false`, monitoring is also stopped for each resolved signal; when omitted, the project's default applies.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "resolveSignals", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveSignalsBody" } } } }, "responses": { "200": { "description": "Per-signal result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignalsLifecycleResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/signals/unresolve": { "post": { "tags": [ "Signals" ], "x-fern-sdk-group-name": "signals", "x-fern-sdk-method-name": "unresolve", "summary": "Unresolve signals", "description": "Reverts each signal in `signalIds` to the unresolved state.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "unresolveSignals", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignalsLifecycleBody" } } } }, "responses": { "200": { "description": "Per-signal result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignalsLifecycleResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/signals/ignore": { "post": { "tags": [ "Signals" ], "x-fern-sdk-group-name": "signals", "x-fern-sdk-method-name": "ignore", "summary": "Ignore signals", "description": "Marks each signal in `signalIds` as ignored. Monitoring is also stopped for each ignored signal.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "ignoreSignals", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignalsLifecycleBody" } } } }, "responses": { "200": { "description": "Per-signal result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignalsLifecycleResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/signals/unignore": { "post": { "tags": [ "Signals" ], "x-fern-sdk-group-name": "signals", "x-fern-sdk-method-name": "unignore", "summary": "Unignore signals", "description": "Reverts each signal in `signalIds` to a non-ignored state.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "unignoreSignals", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignalsLifecycleBody" } } } }, "responses": { "200": { "description": "Per-signal result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignalsLifecycleResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/signals/{signalSlug}/monitor": { "post": { "tags": [ "Signals" ], "x-fern-sdk-group-name": "signals", "x-fern-sdk-method-name": "monitor", "summary": "Monitor signal", "description": "Starts (or realigns) monitoring for the signal. When the signal has no active evaluation, a new one is generated. When an active evaluation exists, the call realigns it. The work runs asynchronously and the response returns immediately. Returns 400 when monitoring is already in progress for this signal.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "monitorSignal", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" }, { "schema": { "type": "string", "description": "Signal slug." }, "required": true, "description": "Signal slug.", "name": "signalSlug", "in": "path" } ], "responses": { "202": { "description": "Monitor job enqueued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitorSignalResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/signals/{signalSlug}/unmonitor": { "post": { "tags": [ "Signals" ], "x-fern-sdk-group-name": "signals", "x-fern-sdk-method-name": "unmonitor", "summary": "Unmonitor signal", "description": "Stops monitoring the signal. Idempotent — signals that aren't being monitored return 204 without changing anything.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "unmonitorSignal", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" }, { "schema": { "type": "string", "description": "Signal slug." }, "required": true, "description": "Signal slug.", "name": "signalSlug", "in": "path" } ], "responses": { "204": { "description": "Signal unmonitored" } } } }, "/v1/projects/{projectSlug}/signals/export": { "post": { "tags": [ "Signals" ], "x-fern-sdk-group-name": "signals", "x-fern-sdk-method-name": "export", "summary": "Export project signals (async)", "description": "Enqueues an asynchronous CSV export. The response returns immediately; the download link is emailed to `recipient` when the file is ready. The recipient must be a member of the requesting organization.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "exportSignals", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportSignalsBody" } } } }, "responses": { "202": { "description": "Export enqueued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportSignalsResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/incidents": { "get": { "tags": [ "Incidents" ], "x-fern-sdk-group-name": "incidents", "x-fern-sdk-method-name": "list", "summary": "List project incidents", "description": "Returns incidents in the project, ordered from oldest to newest. The time window defaults to the trailing 7 days.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "listIncidents", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" }, { "schema": { "type": "string", "format": "date-time", "description": "Lower bound (inclusive) of the time window. Returns incidents whose lifetime overlaps `[fromIso, toIso]`. Defaults to 7 days before `toIso`." }, "required": false, "description": "Lower bound (inclusive) of the time window. Returns incidents whose lifetime overlaps `[fromIso, toIso]`. Defaults to 7 days before `toIso`.", "name": "fromIso", "in": "query" }, { "schema": { "type": "string", "format": "date-time", "description": "Upper bound (inclusive) of the time window. Defaults to now." }, "required": false, "description": "Upper bound (inclusive) of the time window. Defaults to now.", "name": "toIso", "in": "query" }, { "schema": { "type": "array", "items": { "type": "string", "enum": [ "issue", "savedSearch" ] }, "description": "Restrict to incidents whose source type matches any value in this list." }, "required": false, "description": "Restrict to incidents whose source type matches any value in this list.", "name": "sourceTypes", "in": "query" }, { "schema": { "type": "string", "minLength": 24, "maxLength": 24, "description": "Restrict to incidents tied to a single source entity (e.g. one issue id)." }, "required": false, "description": "Restrict to incidents tied to a single source entity (e.g. one issue id).", "name": "sourceId", "in": "query" }, { "schema": { "type": "array", "items": { "type": "string", "enum": [ "issue.new", "issue.regressed", "issue.escalating", "savedSearch.match", "savedSearch.threshold", "savedSearch.escalating", "event.matched", "metric.threshold", "metric.escalating" ] }, "description": "Restrict to incidents whose kind matches any value in this list." }, "required": false, "description": "Restrict to incidents whose kind matches any value in this list.", "name": "kinds", "in": "query" }, { "schema": { "type": "array", "items": { "type": "string", "enum": [ "low", "medium", "high" ] }, "description": "Restrict to incidents whose severity matches any value in this list." }, "required": false, "description": "Restrict to incidents whose severity matches any value in this list.", "name": "severities", "in": "query" } ], "responses": { "200": { "description": "Matching incidents", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListIncidentsResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/incidents/{incidentId}": { "post": { "tags": [ "Incidents" ], "x-fern-sdk-group-name": "incidents", "x-fern-sdk-method-name": "resolve", "summary": "Resolve incident", "description": "Resolves (closes) an ongoing incident. An already-closed incident is returned unchanged. If the incident's condition triggers again, a new incident will be opened.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "resolveIncident", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" }, { "schema": { "type": "string", "minLength": 24, "maxLength": 24, "description": "Incident identifier." }, "required": true, "description": "Incident identifier.", "name": "incidentId", "in": "path" } ], "responses": { "200": { "description": "Resolved incident", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Incident" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/datasets": { "get": { "tags": [ "Datasets" ], "x-fern-sdk-group-name": "datasets", "x-fern-sdk-method-name": "list", "summary": "List project datasets", "description": "Returns a cursor-paginated page of datasets in the project.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "listDatasets", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" }, { "schema": { "type": "string", "description": "Opaque cursor returned in a previous response's `nextCursor`. Omit on the first page." }, "required": false, "description": "Opaque cursor returned in a previous response's `nextCursor`. Omit on the first page.", "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50, "description": "Page size. Defaults to 50; max 200." }, "required": false, "description": "Page size. Defaults to 50; max 200.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "enum": [ "name", "updatedAt" ], "default": "updatedAt", "description": "Field to sort by. Defaults to `updatedAt`." }, "required": false, "description": "Field to sort by. Defaults to `updatedAt`.", "name": "sortBy", "in": "query" }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc", "description": "Sort direction. Defaults to `desc`." }, "required": false, "description": "Sort direction. Defaults to `desc`.", "name": "sortDirection", "in": "query" } ], "responses": { "200": { "description": "Page of datasets", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedDatasets" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Datasets" ], "x-fern-sdk-group-name": "datasets", "x-fern-sdk-method-name": "create", "summary": "Create dataset", "description": "Creates an empty dataset in the project. The slug is derived from `name`.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "createDataset", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDatasetBody" } } } }, "responses": { "201": { "description": "Created dataset", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Dataset" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/datasets/{datasetSlug}": { "get": { "tags": [ "Datasets" ], "x-fern-sdk-group-name": "datasets", "x-fern-sdk-method-name": "get", "summary": "Get project dataset", "description": "Returns one dataset by slug.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "getDataset", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" }, { "schema": { "type": "string", "description": "Dataset slug (human-readable identifier within the project)." }, "required": true, "description": "Dataset slug (human-readable identifier within the project).", "name": "datasetSlug", "in": "path" } ], "responses": { "200": { "description": "Dataset", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Dataset" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "tags": [ "Datasets" ], "x-fern-sdk-group-name": "datasets", "x-fern-sdk-method-name": "update", "summary": "Update dataset", "description": "Updates a dataset's `name` and/or `description`. Renaming regenerates the slug — clients should re-read the response or rely on the `id` for stable references.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "updateDataset", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" }, { "schema": { "type": "string", "description": "Dataset slug (human-readable identifier within the project)." }, "required": true, "description": "Dataset slug (human-readable identifier within the project).", "name": "datasetSlug", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateDatasetBody" } } } }, "responses": { "200": { "description": "Updated dataset", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Dataset" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Datasets" ], "x-fern-sdk-group-name": "datasets", "x-fern-sdk-method-name": "delete", "summary": "Delete dataset", "description": "Deletes a dataset by slug.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "deleteDataset", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" }, { "schema": { "type": "string", "description": "Dataset slug (human-readable identifier within the project)." }, "required": true, "description": "Dataset slug (human-readable identifier within the project).", "name": "datasetSlug", "in": "path" } ], "responses": { "204": { "description": "Dataset deleted" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/datasets/{datasetSlug}/rows": { "get": { "tags": [ "Datasets" ], "x-fern-sdk-group-name": "datasets", "x-fern-sdk-method-name": "listRows", "summary": "List dataset rows", "description": "Returns a cursor-paginated page of rows.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "listDatasetRows", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" }, { "schema": { "type": "string", "description": "Dataset slug (human-readable identifier within the project)." }, "required": true, "description": "Dataset slug (human-readable identifier within the project).", "name": "datasetSlug", "in": "path" }, { "schema": { "type": "string", "description": "Opaque cursor returned in a previous response's `nextCursor`. Omit on the first page." }, "required": false, "description": "Opaque cursor returned in a previous response's `nextCursor`. Omit on the first page.", "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50, "description": "Page size. Defaults to 50; max 200." }, "required": false, "description": "Page size. Defaults to 50; max 200.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Free-text search against row cells." }, "required": false, "description": "Free-text search against row cells.", "name": "search", "in": "query" }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc", "description": "Sort direction on `createdAt`. Defaults to `desc` (newest first)." }, "required": false, "description": "Sort direction on `createdAt`. Defaults to `desc` (newest first).", "name": "sortDirection", "in": "query" } ], "responses": { "200": { "description": "Page of rows", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedDatasetRows" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Datasets" ], "x-fern-sdk-group-name": "datasets", "x-fern-sdk-method-name": "insertRows", "summary": "Insert dataset rows", "description": "Appends one or more rows to the dataset.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "insertDatasetRows", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" }, { "schema": { "type": "string", "description": "Dataset slug (human-readable identifier within the project)." }, "required": true, "description": "Dataset slug (human-readable identifier within the project).", "name": "datasetSlug", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InsertDatasetRowsBody" } } } }, "responses": { "201": { "description": "Rows inserted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InsertDatasetRowsResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Datasets" ], "x-fern-sdk-group-name": "datasets", "x-fern-sdk-method-name": "deleteRows", "summary": "Delete dataset rows", "description": "Deletes rows matching the supplied selection.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "deleteDatasetRows", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" }, { "schema": { "type": "string", "description": "Dataset slug (human-readable identifier within the project)." }, "required": true, "description": "Dataset slug (human-readable identifier within the project).", "name": "datasetSlug", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteDatasetRowsBody" } } } }, "responses": { "200": { "description": "Rows deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteDatasetRowsResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/datasets/{datasetSlug}/rows/import/traces": { "post": { "tags": [ "Datasets" ], "x-fern-sdk-group-name": "datasets", "x-fern-sdk-method-name": "importRowsFromTraces", "summary": "Import dataset rows from traces", "description": "Imports one row per trace matched by `traces`.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "importDatasetRowsFromTraces", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" }, { "schema": { "type": "string", "description": "Dataset slug (human-readable identifier within the project)." }, "required": true, "description": "Dataset slug (human-readable identifier within the project).", "name": "datasetSlug", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportRowsFromTracesBody" } } } }, "responses": { "201": { "description": "Rows imported", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportRowsFromTracesResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/datasets/{datasetSlug}/rows/export": { "post": { "tags": [ "Datasets" ], "x-fern-sdk-group-name": "datasets", "x-fern-sdk-method-name": "exportRows", "summary": "Export dataset rows", "description": "Exports the selected rows as CSV. Returns one of three outcomes, discriminated by `status`:\n\n- `\"ready\"` — the export fit in the synchronous path. Body carries a short-lived signed `downloadUrl` the caller follows with a plain HTTP GET.\n- `\"queued\"` — the export was too large for the synchronous path AND a `recipient` was supplied. The CSV will be emailed to that address. The recipient must be a member of the requesting organization.\n- `\"too_large\"` — the export was too large for the synchronous path AND no `recipient` was supplied. Body includes a `recommendedAction` describing how to recover (typically: ask the user for an email and retry with `recipient` set).", "security": [ { "ApiKeyAuth": [] } ], "operationId": "exportDatasetRows", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" }, { "schema": { "type": "string", "description": "Dataset slug (human-readable identifier within the project)." }, "required": true, "description": "Dataset slug (human-readable identifier within the project).", "name": "datasetSlug", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportDatasetRowsBody" } } } }, "responses": { "200": { "description": "CSV ready at the signed URL", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportDatasetRowsReadyResponse" } } } }, "202": { "description": "Export queued; download link will be emailed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportDatasetRowsQueuedResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Export exceeds the synchronous threshold and no `recipient` was provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportDatasetRowsTooLargeResponse" } } } } } } }, "/v1/api-keys": { "post": { "tags": [ "API Keys" ], "x-fern-sdk-group-name": "apiKeys", "x-fern-sdk-method-name": "create", "summary": "Generate API key", "description": "Generates a new API key for the organization. The token is only returned once — store it securely.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "createApiKey", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApiKeyBody" } } } }, "responses": { "201": { "description": "API key generated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKey" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "tags": [ "API Keys" ], "x-fern-sdk-group-name": "apiKeys", "x-fern-sdk-method-name": "list", "summary": "List API keys", "description": "Returns all API keys for the organization. Tokens are not included in the list response.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "listApiKeys", "responses": { "200": { "description": "List of API keys", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyList" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/api-keys/{apiKeyId}": { "get": { "tags": [ "API Keys" ], "x-fern-sdk-group-name": "apiKeys", "x-fern-sdk-method-name": "get", "summary": "Get API key", "description": "Returns a single API key including the full unmasked `token`. Useful for retrieving a stored token by id without rotating it.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "getApiKey", "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "API-key identifier." }, "required": true, "description": "API-key identifier.", "name": "apiKeyId", "in": "path" } ], "responses": { "200": { "description": "API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKey" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "tags": [ "API Keys" ], "x-fern-sdk-group-name": "apiKeys", "x-fern-sdk-method-name": "update", "summary": "Update API key", "description": "Renames an API key. The token itself is immutable — use create + revoke if you need a new value.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "updateApiKey", "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "API-key identifier." }, "required": true, "description": "API-key identifier.", "name": "apiKeyId", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateApiKeyBody" } } } }, "responses": { "200": { "description": "API key updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKey" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "API Keys" ], "x-fern-sdk-group-name": "apiKeys", "x-fern-sdk-method-name": "revoke", "summary": "Revoke API key", "description": "Revokes an API key.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "revokeApiKey", "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "API-key identifier." }, "required": true, "description": "API-key identifier.", "name": "apiKeyId", "in": "path" } ], "responses": { "204": { "description": "API key revoked" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/oauth-keys": { "get": { "tags": [ "OAuth Keys" ], "x-fern-sdk-group-name": "oauthKeys", "x-fern-sdk-method-name": "list", "summary": "List OAuth keys", "description": "Returns every OAuth key (like MCP clients) connected to the organization.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "listOAuthKeys", "responses": { "200": { "description": "List of OAuth keys", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthKeyList" } } } } } } }, "/v1/oauth-keys/{oauthKeyId}": { "get": { "tags": [ "OAuth Keys" ], "x-fern-sdk-group-name": "oauthKeys", "x-fern-sdk-method-name": "get", "summary": "Get OAuth key", "description": "Returns a single OAuth key (like MCP clients) by id.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "getOAuthKey", "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "OAuth key identifier." }, "required": true, "description": "OAuth key identifier.", "name": "oauthKeyId", "in": "path" } ], "responses": { "200": { "description": "OAuth key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthKey" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "OAuth Keys" ], "x-fern-sdk-group-name": "oauthKeys", "x-fern-sdk-method-name": "revoke", "summary": "Revoke OAuth key", "description": "Revokes an OAuth key (like MCP clients). The connected client immediately loses access.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "revokeOAuthKey", "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "OAuth key identifier." }, "required": true, "description": "OAuth key identifier.", "name": "oauthKeyId", "in": "path" } ], "responses": { "204": { "description": "OAuth key revoked" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/account": { "get": { "tags": [ "Account" ], "x-fern-sdk-group-name": "account", "x-fern-sdk-method-name": "get", "summary": "Get account", "description": "Returns the caller's account snapshot: the organization the request is scoped to, plus the user record and their role when the request was made by a real user (OAuth). API-key callers receive `user: null` and `role: null` because API keys aren't tied to a specific user.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "getAccount", "responses": { "200": { "description": "Account snapshot", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/members": { "get": { "tags": [ "Members" ], "x-fern-sdk-group-name": "members", "x-fern-sdk-method-name": "list", "summary": "List members", "description": "Returns every active member of the caller's organization with their role and user details.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "listMembers", "responses": { "200": { "description": "List of members", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemberList" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Members" ], "x-fern-sdk-group-name": "members", "x-fern-sdk-method-name": "invite", "summary": "Invite a member", "description": "Signals an invitation to join the caller's organization. The invitee receives an accept link by email and becomes a member once they accept. The response is the pending invitation record. Requires OAuth authentication (API-key callers can't act on behalf of a specific user).", "security": [ { "ApiKeyAuth": [] } ], "operationId": "inviteMember", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InviteMemberBody" } } } }, "responses": { "201": { "description": "Invitation created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvitedMember" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/members/{memberId}": { "get": { "tags": [ "Members" ], "x-fern-sdk-group-name": "members", "x-fern-sdk-method-name": "get", "summary": "Get member", "description": "Returns a single member of the caller's organization, including their role and user details.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "getMember", "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "Membership identifier." }, "required": true, "description": "Membership identifier.", "name": "memberId", "in": "path" } ], "responses": { "200": { "description": "Member", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActiveMember" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "tags": [ "Members" ], "x-fern-sdk-group-name": "members", "x-fern-sdk-method-name": "update", "summary": "Update a member", "description": "Updates a member of the caller's organization. Today only the role is mutable. The caller must be an admin or owner; owners cannot be demoted via this endpoint. Requires OAuth authentication.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "updateMember", "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "Membership identifier." }, "required": true, "description": "Membership identifier.", "name": "memberId", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMemberRoleBody" } } } }, "responses": { "200": { "description": "Member with the updated role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActiveMember" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Members" ], "x-fern-sdk-group-name": "members", "x-fern-sdk-method-name": "remove", "summary": "Remove a member", "description": "Removes a member from the caller's organization. Self-removal and removing the organization owner are rejected — transfer ownership first. Requires OAuth authentication.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "removeMember", "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "Membership identifier." }, "required": true, "description": "Membership identifier.", "name": "memberId", "in": "path" } ], "responses": { "204": { "description": "Member removed" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/monitors": { "get": { "tags": [ "Monitors" ], "x-fern-sdk-group-name": "monitors", "x-fern-sdk-method-name": "list", "summary": "List monitors", "description": "Returns the project's monitors, system monitors first, then by most recent activity.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "listMonitors", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" }, { "schema": { "type": "string", "description": "Opaque cursor returned in a previous response's `nextCursor`. Omit on the first page." }, "required": false, "description": "Opaque cursor returned in a previous response's `nextCursor`. Omit on the first page.", "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Page size. Defaults to 50; max 100." }, "required": false, "description": "Page size. Defaults to 50; max 100.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "description": "Filter by name (case-insensitive substring)." }, "required": false, "description": "Filter by name (case-insensitive substring).", "name": "search", "in": "query" } ], "responses": { "200": { "description": "Page of monitors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedMonitors" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Monitors" ], "x-fern-sdk-group-name": "monitors", "x-fern-sdk-method-name": "create", "summary": "Create monitor", "description": "Creates a monitor with one alert. Saved-search alerts use a saved-search source; tool and user alerts use `event.*` or `metric.*` kinds with `source: null` and a `target`. The slug is derived from `name`.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "createMonitor", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMonitorBody" } } } }, "responses": { "201": { "description": "Monitor created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Monitor" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/monitors/for-target": { "post": { "tags": [ "Monitors" ], "x-fern-sdk-group-name": "monitors", "x-fern-sdk-method-name": "listForTarget", "summary": "List monitors for target", "description": "Returns live unified monitors whose target contains the supplied user or tool filter. Use `stream: traces` with a `userId` filter for users, or `stream: spans` with `operation = execute_tool` and `toolName` filters for tools.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "listMonitorsForTarget", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListMonitorsForTargetBody" } } } }, "responses": { "200": { "description": "Matching monitors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitorList" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/monitors/{monitorSlug}": { "get": { "tags": [ "Monitors" ], "x-fern-sdk-group-name": "monitors", "x-fern-sdk-method-name": "get", "summary": "Get monitor", "description": "Returns a single monitor by slug.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "getMonitor", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" }, { "schema": { "type": "string", "description": "Monitor slug (human-readable identifier within the project)." }, "required": true, "description": "Monitor slug (human-readable identifier within the project).", "name": "monitorSlug", "in": "path" } ], "responses": { "200": { "description": "Monitor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Monitor" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "tags": [ "Monitors" ], "x-fern-sdk-group-name": "monitors", "x-fern-sdk-method-name": "update", "summary": "Update monitor", "description": "Updates a monitor's name and description. System monitors cannot be edited.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "updateMonitor", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" }, { "schema": { "type": "string", "description": "Monitor slug (human-readable identifier within the project)." }, "required": true, "description": "Monitor slug (human-readable identifier within the project).", "name": "monitorSlug", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMonitorBody" } } } }, "responses": { "200": { "description": "Updated monitor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Monitor" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "System monitors cannot be edited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Monitors" ], "x-fern-sdk-group-name": "monitors", "x-fern-sdk-method-name": "delete", "summary": "Delete monitor", "description": "Deletes a monitor and its alerts. System monitors cannot be deleted.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "deleteMonitor", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" }, { "schema": { "type": "string", "description": "Monitor slug (human-readable identifier within the project)." }, "required": true, "description": "Monitor slug (human-readable identifier within the project).", "name": "monitorSlug", "in": "path" } ], "responses": { "204": { "description": "Monitor deleted" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/monitors/{monitorSlug}/alerts": { "get": { "tags": [ "Monitors" ], "x-fern-sdk-group-name": "monitors", "x-fern-sdk-method-name": "listAlerts", "summary": "List monitor alerts", "description": "Returns the monitor's alerts.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "listMonitorAlerts", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" }, { "schema": { "type": "string", "description": "Monitor slug (human-readable identifier within the project)." }, "required": true, "description": "Monitor slug (human-readable identifier within the project).", "name": "monitorSlug", "in": "path" } ], "responses": { "200": { "description": "The monitor's alerts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitorAlertList" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/monitors/{monitorSlug}/alerts/{alertId}": { "get": { "tags": [ "Monitors" ], "x-fern-sdk-group-name": "monitors", "x-fern-sdk-method-name": "getAlert", "summary": "Get monitor alert", "description": "Returns a single monitor alert by id.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "getMonitorAlert", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" }, { "schema": { "type": "string", "description": "Monitor slug (human-readable identifier within the project)." }, "required": true, "description": "Monitor slug (human-readable identifier within the project).", "name": "monitorSlug", "in": "path" }, { "schema": { "type": "string", "description": "Monitor-alert identifier." }, "required": true, "description": "Monitor-alert identifier.", "name": "alertId", "in": "path" } ], "responses": { "200": { "description": "Monitor alert", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitorAlert" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "tags": [ "Monitors" ], "x-fern-sdk-group-name": "monitors", "x-fern-sdk-method-name": "updateAlert", "summary": "Update monitor alert", "description": "Updates an alert and returns the updated monitor. On system monitors only the condition may change; on your own monitors any field may. Saved-search alerts use a source; tool and user alerts use `source: null` with the monitor target.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "updateMonitorAlert", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" }, { "schema": { "type": "string", "description": "Monitor slug (human-readable identifier within the project)." }, "required": true, "description": "Monitor slug (human-readable identifier within the project).", "name": "monitorSlug", "in": "path" }, { "schema": { "type": "string", "description": "Monitor-alert identifier." }, "required": true, "description": "Monitor-alert identifier.", "name": "alertId", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMonitorAlertBody" } } } }, "responses": { "200": { "description": "Monitor with the updated alert", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Monitor" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Disallowed change on a system monitor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/monitors/{monitorSlug}/incidents": { "get": { "tags": [ "Monitors" ], "x-fern-sdk-group-name": "monitors", "x-fern-sdk-method-name": "listIncidents", "summary": "List monitor incidents", "description": "Returns the incidents opened by a monitor, most recent first. Each item's `notified` flag shows whether it triggered a notification.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "listMonitorIncidents", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" }, { "schema": { "type": "string", "description": "Monitor slug (human-readable identifier within the project)." }, "required": true, "description": "Monitor slug (human-readable identifier within the project).", "name": "monitorSlug", "in": "path" }, { "schema": { "type": "string", "description": "Opaque cursor returned in a previous response's `nextCursor`. Omit on the first page." }, "required": false, "description": "Opaque cursor returned in a previous response's `nextCursor`. Omit on the first page.", "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Page size. Defaults to 50; max 100." }, "required": false, "description": "Page size. Defaults to 50; max 100.", "name": "limit", "in": "query" } ], "responses": { "200": { "description": "Page of incidents", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedMonitorIncidents" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/monitors/{monitorSlug}/mute": { "post": { "tags": [ "Monitors" ], "x-fern-sdk-group-name": "monitors", "x-fern-sdk-method-name": "mute", "summary": "Mute monitor", "description": "Mutes a monitor so its incidents stop sending notifications. Allowed on all monitors.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "muteMonitor", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" }, { "schema": { "type": "string", "description": "Monitor slug (human-readable identifier within the project)." }, "required": true, "description": "Monitor slug (human-readable identifier within the project).", "name": "monitorSlug", "in": "path" } ], "responses": { "200": { "description": "Muted monitor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Monitor" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/monitors/{monitorSlug}/unmute": { "post": { "tags": [ "Monitors" ], "x-fern-sdk-group-name": "monitors", "x-fern-sdk-method-name": "unmute", "summary": "Unmute monitor", "description": "Lifts a monitor's mute so its incidents notify again.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "unmuteMonitor", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" }, { "schema": { "type": "string", "description": "Monitor slug (human-readable identifier within the project)." }, "required": true, "description": "Monitor slug (human-readable identifier within the project).", "name": "monitorSlug", "in": "path" } ], "responses": { "200": { "description": "Unmuted monitor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Monitor" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "webhooks": {} }