{ "openapi": "3.1.0", "info": { "title": "Latitude", "version": "v1", "description": "Open-source AI agent monitoring platform. Full observability into what's failing in production. Discover underlying issues, get alerts when something breaks and verify your fix worked." }, "servers": [ { "url": "https://api.latitude.so", "description": "Production" } ], "components": { "securitySchemes": { "ApiKeyAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API key", "description": "Organization-scoped API key, sent as `Authorization: Bearer `.", "x-fern-bearer": { "name": "apiKey", "env": "LATITUDE_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" ] }, "BootstrapAccountResponse": { "type": "object", "properties": { "organizationSlug": { "type": "string", "description": "Slug of the temporary organization." }, "projectSlug": { "type": "string", "description": "Slug of the created project." }, "apiKey": { "type": "string", "description": "Organization-scoped API key." }, "claimUrl": { "type": "string", "description": "URL to open in a browser to claim ownership of the organization." }, "claimEmail": { "type": [ "string", "null" ], "description": "Email address the claim link will be sent to, or `null` if none was provided." }, "claimExpiresAt": { "type": "string", "description": "ISO-8601 timestamp when the claim link expires. The organization is deleted if not claimed by then." } }, "required": [ "organizationSlug", "projectSlug", "apiKey", "claimUrl", "claimEmail", "claimExpiresAt" ] }, "Error": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "BootstrapAccountBody": { "type": "object", "properties": { "organizationName": { "type": "string", "description": "Name for the temporary organization. If not provided, defaults to \"My Organization\"." }, "projectName": { "type": "string", "description": "Name for the project created in the organization. If not provided, defaults to \"My Project\"." }, "userEmail": { "type": "string", "format": "email", "description": "Email address to send the claim link to." } } }, "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." }, "redaction": { "$ref": "#/components/schemas/RedactionSetting" }, "notifications": { "$ref": "#/components/schemas/NotificationsSetting" }, "escalation": { "$ref": "#/components/schemas/EscalationSetting" } }, "description": "Per-project settings overrides. `null` means inherit from the organization." }, "RedactionSetting": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "off", "enforce" ], "description": "`enforce` scans span content as it is ingested and replaces matches with a labelled placeholder such as `[REDACTED_EMAIL]`; `off` scans nothing. Defaults to `off` when omitted. Applies only to spans ingested after the change, takes effect within a minute, and redacted content cannot be recovered." }, "entities": { "type": "array", "items": { "type": "string", "enum": [ "email", "phone", "credit_card", "iban", "us_ssn", "ip_address", "secret" ] }, "maxItems": 7, "description": "Which categories to look for. Defaults to email, phone, credit_card, iban, us_ssn, secret when omitted; `ip_address` is off by default because a dotted quad and a four-part version string are the same string. Detection is pattern based: it reliably catches structured identifiers, and does not catch names, addresses, or free-form personal detail." }, "scopes": { "type": "object", "properties": { "metadata": { "type": "boolean", "description": "Also scan the metadata map and tags. Defaults to `false` when omitted, because metadata is usually operational and redacting it removes values you filter and group by." } }, "description": "Which span fields to scan beyond message and tool content." }, "identities": { "type": "string", "enum": [ "keep", "pseudonymize" ], "description": "How to handle `userId` and `userEmail`. `keep` stores them unchanged; `pseudonymize` replaces each with a stable per-organization pseudonym so filtering and grouping by user keep working. Defaults to `keep` when omitted. Deployments with no pseudonym secret configured remove the identifier entirely instead." } }, "description": "Server-side PII redaction applied before spans are stored. An organization-wide policy can override this one; when the organization locks its policy, project values are ignored entirely rather than merged." }, "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": { "signal.escalating": { "type": "boolean", "description": "Send a notification when an active signal is escalating in volume or severity. Defaults to `true` when omitted." }, "monitor.match": { "type": "boolean", "description": "Send a notification when a match monitor opens an incident. Defaults to `true` when omitted." }, "monitor.threshold": { "type": "boolean", "description": "Send a notification when a threshold monitor opens an incident. Defaults to `true` when omitted." }, "monitor.escalating": { "type": "boolean", "description": "Send a notification when an escalating monitor opens an incident. 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." }, "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": { "$ref": "#/components/schemas/ProjectSettingsPatch" }, "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" }, "bluffing": { "type": "boolean" }, "pii-leakage": { "type": "boolean" }, "incompletion": { "type": "boolean" }, "tool-call-errors": { "type": "boolean" }, "output-schema-validation": { "type": "boolean" }, "empty-response": { "type": "boolean" }, "low-cache-hit-rate": { "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." } } }, "ProjectSettingsPatch": { "type": "object", "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." }, "redaction": { "$ref": "#/components/schemas/RedactionSetting" }, "notifications": { "$ref": "#/components/schemas/NotificationsSetting" }, "escalation": { "$ref": "#/components/schemas/EscalationSetting" } }, "description": "Patch the project's settings overrides. Only the fields you send are changed; omitted fields keep their stored values. To clear overrides entirely, edit via the web UI." }, "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 a CUID for 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/TraceFilterSet" } } }, "TraceFilterSet": { "type": "object", "additionalProperties": { "type": "array", "items": { "$ref": "#/components/schemas/FilterCondition" } }, "description": "Filter set keyed by trace field. Each entry holds an array of conditions ANDed together for that field; field-level groups are ANDed across the set. Valid fields: status, name, traceId, sessionId, simulationId, userId, tags, models, providers, serviceNames, tools, definedTools, duration, ttft, cost, spanCount, errorCount, tokensInput, tokensOutput, cacheHitRate, startTime, endTime; score-derived keys (score.passed, score.errored, score.value, score.source, score.sourceId, score.annotatorId, score.signalId, score.simulationId); and arbitrary metadata via `metadata.`. `startTime`/`endTime` take ISO-8601 values (a trace's first span start / last span end). `gtePercentile` is only supported on duration/ttft/cost — not on time fields. Unknown fields are rejected rather than ignored." }, "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." }, "conversation": { "type": "array", "items": { "$ref": "#/components/schemas/GenAIMessage" }, "description": "Full conversation for the trace, in OpenTelemetry GenAI format: the system instructions, then the messages sent into the trace's last LLM-completion span (the running history at that point), followed by that span's generated output." } }, "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", "conversation" ] }, "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" ] }, "SessionMemorySummary": { "type": "object", "properties": { "records": { "type": "array", "items": { "$ref": "#/components/schemas/MemoryRecordSummary" }, "description": "Per-record read/write token footprint for the session (or a single trace)." }, "total": { "type": "object", "properties": { "readTokens": { "type": "integer", "minimum": 0, "description": "Total tokens read across the session." }, "tokensAdded": { "type": "integer", "minimum": 0, "description": "Total tokens added across the session." }, "tokensRemoved": { "type": "integer", "minimum": 0, "description": "Total tokens removed across the session." }, "writeRecords": { "type": "integer", "minimum": 0, "description": "Number of records the session wrote, including zero-delta writes." } }, "required": [ "readTokens", "tokensAdded", "tokensRemoved", "writeRecords" ], "description": "Session-wide totals." } }, "required": [ "records", "total" ] }, "MemoryRecordSummary": { "type": "object", "properties": { "storeId": { "type": "string", "description": "Store the record belongs to." }, "recordId": { "type": "string", "description": "Record the metrics are for." }, "readTokens": { "type": "integer", "minimum": 0, "description": "Tokens read from this record across the session's retrievals." }, "tokensAdded": { "type": "integer", "minimum": 0, "description": "Tokens the session added to this record (endpoint diff)." }, "tokensRemoved": { "type": "integer", "minimum": 0, "description": "Tokens the session removed from this record (endpoint diff)." } }, "required": [ "storeId", "recordId", "readTokens", "tokensAdded", "tokensRemoved" ] }, "SessionMemoryChanges": { "type": "object", "properties": { "records": { "type": "array", "items": { "$ref": "#/components/schemas/SessionMemoryChange" }, "description": "Per-record before/after diffs for what the session changed." } }, "required": [ "records" ] }, "SessionMemoryChange": { "type": "object", "properties": { "storeId": { "type": "string", "description": "Store the changed record belongs to." }, "recordId": { "type": "string", "description": "Record that changed." }, "kind": { "type": "string", "enum": [ "added", "updated", "removed" ], "description": "How the session changed the record." }, "beforeBody": { "type": [ "string", "null" ], "description": "The record's body before the session's writes. `null` when added or when the prior body was not captured." }, "afterBody": { "type": [ "string", "null" ], "description": "The record's body after the session's writes. `null` when removed or when the body was not captured." }, "tokensAdded": { "type": "integer", "minimum": 0, "description": "Tokens added by the session's writes." }, "tokensRemoved": { "type": "integer", "minimum": 0, "description": "Tokens removed by the session's writes." }, "degraded": { "type": "boolean", "description": "`true` when a side's body was unavailable, so the diff is incomplete." }, "lastChangeSpanId": { "type": [ "string", "null" ], "description": "Span of the session's last write to this record. `null` when unknown." } }, "required": [ "storeId", "recordId", "kind", "beforeBody", "afterBody", "tokensAdded", "tokensRemoved", "degraded", "lastChangeSpanId" ] }, "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" ] }, "UserMemoryStores": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/MemoryUserStore" }, "description": "Memory stores the user accessed, most recent access first." } }, "required": [ "items" ] }, "MemoryUserStore": { "type": "object", "properties": { "storeId": { "type": "string", "description": "Store the user accessed. The empty string is the unattributed bucket." }, "lastAccessedAt": { "type": "string", "description": "ISO-8601 timestamp of the user's most recent access to the store." } }, "required": [ "storeId", "lastAccessedAt" ] }, "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` + `new`)." }, "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`." }, "regressedAt": { "type": [ "string", "null" ], "description": "ISO-8601 timestamp at which a new occurrence reopened the resolved signal, or `null`." }, "mutedAt": { "type": [ "string", "null" ], "description": "ISO-8601 timestamp at which notifications were muted, or `null`. Muting only silences notifications; incidents still open." }, "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." }, "affectedSessionsPercent": { "type": "number", "minimum": 0, "maximum": 1, "description": "Fraction of project sessions affected by this signal in the time window, in `[0, 1]`." } }, "required": [ "id", "organizationId", "projectId", "slug", "name", "description", "source", "states", "resolvedAt", "ignoredAt", "regressedAt", "mutedAt", "createdAt", "updatedAt", "trend", "tags", "firstSeenAt", "lastSeenAt", "occurrences", "affectedSessionsPercent" ] }, "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" ] }, "CreateSignalResponse": { "type": "object", "properties": { "id": { "type": "string", "minLength": 24, "maxLength": 24, "description": "Created signal id." }, "slug": { "type": "string", "description": "URL-safe identifier; use it on the other signal endpoints." }, "evaluationId": { "type": "string", "minLength": 24, "maxLength": 24, "description": "Id of the signal's detector evaluation." } }, "required": [ "id", "slug", "evaluationId" ] }, "CreateSignalBody": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Human-readable name. Used to derive the slug." }, "description": { "type": "string", "minLength": 1, "description": "What this signal captures." }, "priority": { "type": [ "string", "null" ], "enum": [ "low", "medium", "high", "urgent", null ], "description": "Manual triage priority. Null/omitted leaves it unset." }, "filters": { "type": [ "object", "null" ], "additionalProperties": { "type": "array", "items": { "$ref": "#/components/schemas/FilterCondition" } }, "description": "Row-local pre-gate restricting which traces the evaluation runs against. Omitted = all traces." }, "evaluation": { "anyOf": [ { "type": "object", "properties": { "settings": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "judge" ] }, "criteria": { "type": "string", "minLength": 1 } }, "required": [ "kind", "criteria" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "rule" ] }, "match": { "type": "string", "enum": [ "all", "any" ], "default": "all" }, "conditions": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text_match" ] }, "scope": { "type": "string", "enum": [ "last_assistant", "any_assistant", "any_user", "any_tool", "conversation" ], "default": "last_assistant" }, "operator": { "type": "string", "enum": [ "contains", "not_contains", "matches_regex", "not_matches_regex" ] }, "value": { "type": "string", "minLength": 1 }, "caseSensitive": { "type": "boolean", "default": false } }, "required": [ "type", "operator", "value" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "empty_output" ] } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "output_length" ] }, "unit": { "type": "string", "enum": [ "chars", "words" ], "default": "chars" }, "operator": { "type": "string", "enum": [ "gt", "gte", "lt", "lte" ] }, "value": { "type": "integer", "minimum": 0 } }, "required": [ "type", "operator", "value" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "json_output" ] }, "expectation": { "type": "string", "enum": [ "valid", "invalid" ] } }, "required": [ "type", "expectation" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "metric" ] }, "field": { "type": "string", "enum": [ "duration", "cost", "tokensTotal", "tokensInput", "tokensOutput", "errorCount", "traceCount", "spanCount" ] }, "aggregation": { "type": "string", "enum": [ "session", "anyTrace", "allTraces" ], "default": "session" }, "operator": { "type": "string", "enum": [ "gt", "gte", "lt", "lte" ] }, "value": { "type": "number", "minimum": 0 } }, "required": [ "type", "field", "operator", "value" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "tool_used" ] }, "toolName": { "type": "string", "minLength": 1 } }, "required": [ "type", "toolName" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "tool_failed" ] }, "toolName": { "type": "string", "minLength": 1 } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "tool_call_count" ] }, "operator": { "type": "string", "enum": [ "gt", "gte", "lt", "lte" ] }, "value": { "type": "integer", "minimum": 0 } }, "required": [ "type", "operator", "value" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "error" ] } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "finish_reason" ] }, "value": { "type": "string", "minLength": 1 } }, "required": [ "type", "value" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "semantic_similarity" ] }, "query": { "type": "string", "minLength": 1 }, "operator": { "type": "string", "enum": [ "gt", "gte", "lt", "lte" ], "default": "gte" }, "threshold": { "type": "number", "minimum": 0, "maximum": 1 } }, "required": [ "type", "query", "threshold" ] } ] }, "minItems": 1, "maxItems": 10 } }, "required": [ "kind", "conditions" ] } ], "description": "Declarative detector config. `judge` compiles to an LLM script; `rule` compiles to a deterministic script over the session." } }, "required": [ "settings" ] }, { "type": "object", "properties": { "script": { "type": "string", "minLength": 1, "description": "Raw sandbox evaluation script (advanced). Must compile in the QuickJS runtime." } }, "required": [ "script" ] } ], "description": "The signal's membership detector. Provide exactly one of `settings` or `script`." } }, "required": [ "name", "description", "evaluation" ] }, "UpdateSignalResponse": { "type": "object", "properties": { "id": { "type": "string", "minLength": 24, "maxLength": 24, "description": "Updated signal id." }, "slug": { "type": "string", "description": "URL-safe identifier (stable across updates)." }, "changed": { "type": "boolean", "description": "Whether any field actually changed." } }, "required": [ "id", "slug", "changed" ] }, "UpdateSignalBody": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 128, "description": "New name. Omitted leaves it unchanged." }, "description": { "type": "string", "minLength": 1, "description": "New description. Omitted leaves it unchanged." }, "filters": { "type": [ "object", "null" ], "additionalProperties": { "type": "array", "items": { "$ref": "#/components/schemas/FilterCondition" } }, "description": "New evaluation pre-gate. Explicit `null` clears it; omitted leaves it unchanged." } } }, "SignalAnalyticsResponse": { "type": "object", "properties": { "ongoing": { "$ref": "#/components/schemas/SignalAnalyticsOngoing" }, "new": { "$ref": "#/components/schemas/SignalAnalyticsNew" }, "escalating": { "$ref": "#/components/schemas/SignalAnalyticsEscalating" }, "resolved": { "$ref": "#/components/schemas/SignalAnalyticsResolved" }, "ignored": { "$ref": "#/components/schemas/SignalAnalyticsIgnored" }, "occurrences": { "$ref": "#/components/schemas/SignalAnalyticsOccurrences" } }, "required": [ "ongoing", "new", "escalating", "resolved", "ignored", "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" ] }, "SignalAnalyticsResolved": { "type": "object", "properties": { "total": { "type": "integer", "minimum": 0, "description": "Number of resolved signals." } }, "required": [ "total" ] }, "SignalAnalyticsIgnored": { "type": "object", "properties": { "total": { "type": "integer", "minimum": 0, "description": "Number of ignored 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` + `new`)." }, "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`." }, "regressedAt": { "type": [ "string", "null" ], "description": "ISO-8601 timestamp at which a new occurrence reopened the resolved signal, or `null`." }, "mutedAt": { "type": [ "string", "null" ], "description": "ISO-8601 timestamp at which notifications were muted, or `null`. Muting only silences notifications; incidents still open." }, "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." }, "affectedSessionsPercent": { "type": "number", "minimum": 0, "maximum": 1, "description": "Lifetime fraction of project sessions 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", "regressedAt", "mutedAt", "createdAt", "updatedAt", "trend", "tags", "firstSeenAt", "lastSeenAt", "occurrences", "affectedSessionsPercent", "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", "null" ], "description": "ISO-8601 timestamp at which the evaluation was last realigned, or `null` if never aligned." }, "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", "null" ], "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, or `null` for an unaligned (e.g. raw / deterministic) evaluation." }, "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." }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "failed" ] }, "phase": { "type": "string", "enum": [ "generate", "realign" ], "description": "Which workflow failed: `generate` (creating the evaluation) or `realign` (updating it)." }, "evaluationId": { "type": "string", "minLength": 24, "maxLength": 24, "description": "Id of the evaluation whose realignment failed. Absent when the failure was during `generate`." }, "reason": { "type": [ "string", "null" ], "description": "Resolved failure message, or `null` once Temporal has dropped the failed run." } }, "required": [ "kind", "phase", "reason" ], "description": "The most recent generation or realignment workflow for this signal ended in failure." } ], "description": "Whether the signal is currently being monitored: `automatic`, `idle`, `generating`, `realigning`, or `failed`." }, "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`." }, "regressedAt": { "type": [ "string", "null" ], "description": "ISO-8601 timestamp at which a new occurrence reopened the resolved signal, or `null`." }, "mutedAt": { "type": [ "string", "null" ], "description": "ISO-8601 timestamp at which notifications were muted, or `null`. Ignoring a signal also mutes it." }, "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", "regressedAt", "mutedAt", "updatedAt", "changed" ] }, "ResolveSignalsBody": { "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." }, "keepMonitoring": { "type": "boolean", "description": "Whether linked evaluations keep running after the resolve, so regressions are detected. Defaults to the project setting." } }, "required": [ "signalIds" ] }, "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 unmuted signals; `\"archived\"` for muted signals. 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": [ "monitor", "signal" ], "description": "Kind of entity that triggered the incident: `signal` or `monitor`." }, "sourceId": { "type": "string", "minLength": 24, "maxLength": 24, "description": "Id of the entity that triggered the incident (matches `sourceType`)." }, "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." }, "condition": { "anyOf": [ { "$ref": "#/components/schemas/AlertThresholdCondition" }, { "$ref": "#/components/schemas/AlertEscalatingCondition" }, { "type": "null" } ], "description": "The monitor rule configuration when the incident opened, or `null` for signal incidents and match monitors." } }, "required": [ "id", "organizationId", "projectId", "sourceType", "sourceId", "severity", "startedAt", "endedAt", "createdAt", "condition" ] }, "AlertThresholdCondition": { "type": "object", "properties": { "trigger": { "type": "string", "enum": [ "threshold" ], "description": "Opens once the measured value crosses the 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": [ "trigger", "metric", "threshold" ] }, "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": [ "cacheHitRate" ], "description": "Token-weighted prompt-cache hit rate (cache-read tokens over total input-side tokens), a 0..1 fraction." } }, "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": [ "sum" ], "description": "Sum 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": [ "min" ], "description": "Find the minimum numeric field value 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": [ "max" ], "description": "Find the maximum numeric field value 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": [ "median" ], "description": "Find the median numeric field value 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." }, "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." }, "AlertEscalatingCondition": { "type": "object", "properties": { "trigger": { "type": "string", "enum": [ "escalating" ], "description": "Opens when the monitor target is escalating or sustained." }, "metric": { "$ref": "#/components/schemas/MonitorMetric" }, "threshold": { "allOf": [ { "$ref": "#/components/schemas/AlertMetricThreshold" }, { "description": "How the metric is compared when threshold-based." } ] }, "direction": { "type": "string", "enum": [ "above", "below" ], "description": "Direction that opens the incident. Defaults to `above` when omitted." }, "sensitivity": { "type": "integer", "minimum": 1, "maximum": 6, "description": "Detector sensitivity from 1 (noisiest) to 6 (strictest). Defaults to 3 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": [ "trigger", "metric", "window" ] }, "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." }, "columns": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/DatasetColumn" }, "description": "Ordered column schema (built-in + custom). `null` means the default schema: the four built-in fields, all visible." }, "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", "columns", "version", "createdAt", "updatedAt" ] }, "DatasetColumn": { "type": "object", "properties": { "identifier": { "type": "string", "description": "Stable, immutable column id. The key under which custom values are stored on each row." }, "name": { "type": "string", "description": "Display name. Editable; the identifier never changes." }, "source": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "builtin" ], "description": "A built-in field (`input`, `output`, `expectedOutput`, or `metadata`)." }, "field": { "type": "string", "enum": [ "input", "output", "expectedOutput", "metadata" ], "description": "Which built-in field this column projects." } }, "required": [ "kind", "field" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "custom" ], "description": "A user-added column; its values live under the row's `custom` store." } }, "required": [ "kind" ] } ], "description": "Where the column's values come from." }, "removed": { "type": "boolean", "description": "`true` for soft-removed columns (only returned when listing with `includeRemoved`). Removed columns are excluded from rows and the default schema, but keep their data and can be restored." } }, "required": [ "identifier", "name", "source" ] }, "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": "Input cell. Omitted when the `input` column is removed." }, "output": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": {} }, { "type": "object", "additionalProperties": {} } ], "description": "Output cell. Omitted when the `output` column is removed." }, "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`. Omitted when the `expectedOutput` column is removed." }, "metadata": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": {} }, { "type": "object", "additionalProperties": {} } ], "description": "Metadata cell. Omitted when the `metadata` column is removed." }, "custom": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": {} }, { "type": "object", "additionalProperties": {} } ], "description": "Free-form cell value: any JSON scalar, array, or object." }, "description": "Custom column values keyed by column identifier. Removed columns are excluded; `{}` when none." }, "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", "custom", "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." }, "custom": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": {} }, { "type": "object", "additionalProperties": {} }, { "type": "null" } ] }, "description": "Custom column values keyed by column identifier. Removed or unknown columns are rejected." } }, "required": [ "input" ] }, "minItems": 1, "description": "Rows to insert." } }, "required": [ "rows" ] }, "UpdateDatasetRowResponse": { "type": "object", "properties": { "versionId": { "type": "string", "description": "New dataset version id." }, "version": { "type": "integer", "minimum": 0, "description": "New dataset version number." } }, "required": [ "versionId", "version" ] }, "UpdateDatasetRowBody": { "type": "object", "properties": { "input": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": {} }, { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "New input cell. Omit to leave it unchanged." }, "output": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": {} }, { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "New output cell. Omit to leave it unchanged." }, "expectedOutput": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": {} }, { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "New correct answer for this row. Filled in by curators; usually distinct from `output`. Omit to leave it unchanged." }, "metadata": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": {} }, { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "New metadata cell. Omit to leave it unchanged." }, "custom": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": {} }, { "type": "object", "additionalProperties": {} }, { "type": "null" } ] }, "description": "Custom column values to set, keyed by column identifier. Merged onto the row's existing custom values — columns you omit are left unchanged. Unknown or removed columns are rejected." } } }, "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." } } }, "DatasetColumnsList": { "type": "object", "properties": { "columns": { "type": "array", "items": { "$ref": "#/components/schemas/DatasetColumn" }, "description": "Ordered column schema (built-in + custom)." } }, "required": [ "columns" ] }, "AddDatasetColumnBody": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Display name for the new custom column." } }, "required": [ "name" ] }, "UpdateDatasetColumnBody": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "New display name. Works for both built-in and custom columns." } }, "required": [ "name" ] }, "ReorderDatasetColumnsBody": { "type": "object", "properties": { "order": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "description": "Column identifiers in the desired left-to-right order. Identifiers omitted from the list keep their relative order at the end; unknown identifiers are ignored." } }, "required": [ "order" ] }, "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 auto-provisioned system monitors, which cannot be deleted or edited; `false` otherwise." }, "target": { "$ref": "#/components/schemas/MonitorTarget" }, "rule": { "$ref": "#/components/schemas/MonitorRule" }, "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", "target", "rule", "mutedAt", "deletedAt", "createdAt", "updatedAt" ] }, "MonitorTarget": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "savedSearch", "tool", "user", "session" ], "description": "Product target category: `savedSearch`, `tool`, `user`, or `session`." }, "id": { "type": [ "string", "null" ], "minLength": 24, "maxLength": 24, "description": "Target entity id, or `null` for project-wide targets." }, "filterSet": { "$ref": "#/components/schemas/MonitorFilterSet" }, "query": { "type": [ "string", "null" ], "description": "Semantic query applied when evaluating inline trace targets." }, "kind": { "type": "string", "enum": [ "savedSearch", "tool", "user", "session" ], "description": "Normalized target kind returned on persisted monitors." }, "stream": { "type": "string", "enum": [ "traces", "spans", "sessions" ], "description": "Telemetry stream evaluated by the monitor." }, "savedSearchId": { "type": [ "string", "null" ], "minLength": 24, "maxLength": 24, "description": "Saved-search id for saved-search monitors, or `null` for inline targets." }, "metric": { "allOf": [ { "$ref": "#/components/schemas/MonitorMetric" }, { "description": "Default metric evaluated for this target." } ] } }, "required": [ "type", "id" ], "description": "Entity or filter set watched by this monitor." }, "MonitorFilterSet": { "type": "object", "additionalProperties": { "type": "array", "items": { "$ref": "#/components/schemas/FilterCondition" } }, "description": "Additional filters applied when evaluating the monitor." }, "MonitorRule": { "type": "object", "properties": { "trigger": { "type": "string", "enum": [ "match", "threshold", "escalating" ], "description": "When the monitor opens incidents: `match`, `threshold`, or `escalating`." }, "config": { "$ref": "#/components/schemas/MonitorConfig" }, "severity": { "type": "string", "enum": [ "low", "medium", "high" ], "description": "Severity of incidents this monitor opens: `low`, `medium`, or `high`." } }, "required": [ "trigger", "config", "severity" ], "description": "Single rule evaluated by this monitor." }, "MonitorConfig": { "type": "object", "properties": { "filterSet": { "allOf": [ { "$ref": "#/components/schemas/MonitorFilterSet" }, { "description": "Filters applied by the monitor rule." } ] }, "query": { "type": [ "string", "null" ], "description": "Semantic query applied by inline monitor targets." }, "metric": { "allOf": [ { "$ref": "#/components/schemas/MonitorMetric" }, { "description": "Metric evaluated by threshold and escalating monitor rules." } ] }, "condition": { "$ref": "#/components/schemas/AlertCondition" } }, "description": "Rule configuration used when the monitor is evaluated." }, "AlertCondition": { "oneOf": [ { "$ref": "#/components/schemas/AlertThresholdCondition" }, { "$ref": "#/components/schemas/AlertEscalatingCondition" } ], "discriminator": { "propertyName": "trigger", "mapping": { "threshold": "#/components/schemas/AlertThresholdCondition", "escalating": "#/components/schemas/AlertEscalatingCondition" } }, "description": "Condition that controls threshold or escalating incidents." }, "CreateMonitorBody": { "oneOf": [ { "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." }, "target": { "allOf": [ { "$ref": "#/components/schemas/MonitorTarget" }, { "description": "Entity or filter set watched by the monitor." } ] }, "severity": { "type": "string", "enum": [ "low", "medium", "high" ], "description": "Severity assigned to incidents opened by this monitor." }, "trigger": { "type": "string", "enum": [ "match" ], "description": "Opens a point incident when any matching event appears." }, "metric": { "allOf": [ { "$ref": "#/components/schemas/MonitorMetric" }, { "description": "Metric stored for later rule edits. Match monitors evaluate counts." } ] } }, "required": [ "name", "target", "severity", "trigger" ], "additionalProperties": false }, { "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." }, "target": { "allOf": [ { "$ref": "#/components/schemas/MonitorTarget" }, { "description": "Entity or filter set watched by the monitor." } ] }, "severity": { "type": "string", "enum": [ "low", "medium", "high" ], "description": "Severity assigned to incidents opened by this monitor." }, "trigger": { "type": "string", "enum": [ "threshold" ], "description": "Opens a point incident when the condition is met." }, "metric": { "allOf": [ { "$ref": "#/components/schemas/MonitorMetric" }, { "description": "Metric evaluated by the monitor rule." } ] }, "condition": { "allOf": [ { "$ref": "#/components/schemas/AlertThresholdCondition" }, { "description": "Threshold condition that opens point incidents." } ] } }, "required": [ "name", "target", "severity", "trigger", "condition" ] }, { "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." }, "target": { "allOf": [ { "$ref": "#/components/schemas/MonitorTarget" }, { "description": "Entity or filter set watched by the monitor." } ] }, "severity": { "type": "string", "enum": [ "low", "medium", "high" ], "description": "Severity assigned to incidents opened by this monitor." }, "trigger": { "type": "string", "enum": [ "escalating" ], "description": "Opens and closes a sustained incident while the condition is met." }, "metric": { "allOf": [ { "$ref": "#/components/schemas/MonitorMetric" }, { "description": "Metric evaluated by the monitor rule." } ] }, "condition": { "allOf": [ { "$ref": "#/components/schemas/AlertEscalatingCondition" }, { "description": "Escalating condition that opens sustained incidents." } ] } }, "required": [ "name", "target", "severity", "trigger", "condition" ] } ] }, "MonitorList": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Monitor" }, "description": "Matching monitors." } }, "required": [ "items" ] }, "ListMonitorsForTargetBody": { "type": "object", "properties": { "targetType": { "type": "string", "enum": [ "savedSearch", "tool", "user", "session" ], "description": "Optional target type to match." }, "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": [ "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." }, "severity": { "type": "string", "enum": [ "low", "medium", "high" ], "description": "Replacement incident severity." } } }, "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": [ "monitor", "signal" ], "description": "Kind of entity that triggered the incident: `signal` or `monitor`." }, "sourceId": { "type": "string", "minLength": 24, "maxLength": 24, "description": "Id of the entity that triggered the incident (matches `sourceType`)." }, "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." }, "condition": { "anyOf": [ { "$ref": "#/components/schemas/AlertThresholdCondition" }, { "$ref": "#/components/schemas/AlertEscalatingCondition" }, { "type": "null" } ], "description": "The monitor rule configuration when the incident opened, or `null` for signal incidents and match monitors." }, "notified": { "type": "boolean", "description": "`true` when this incident triggered at least one notification." } }, "required": [ "id", "organizationId", "projectId", "sourceType", "sourceId", "severity", "startedAt", "endedAt", "createdAt", "condition", "notified" ] }, "AnalyticsSeries": { "type": "object", "properties": { "series": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "The breakdown value, present when `breakdown` was set." }, "label": { "type": "string", "description": "Human-readable name for `key` when the breakdown value is an opaque id — the signal name for `signalId`, the cluster name for `cluster`. Absent for already-readable breakdowns." }, "bucketStart": { "type": "string", "description": "ISO-8601 start of the time bucket, present when `timeBucket` was set." }, "value": { "type": "number", "description": "The metric value: seconds for `duration`, dollars for `cost`, a 0–1 ratio for `errorRate`/`cacheHitRate`, otherwise a raw count/token total." } }, "required": [ "value" ] }, "description": "Tidy series: one point per breakdown key and/or time bucket." } }, "required": [ "series" ] }, "AnalyticsQuery": { "oneOf": [ { "type": "object", "properties": { "stream": { "type": "string", "enum": [ "traces" ] }, "query": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Semantic search query, combined with `filters` via AND. Ranks/filters by relevance." }, "breakdown": { "type": "string", "enum": [ "model", "provider", "service", "tool", "tag", "name", "userId", "status" ], "description": "Dimension to group by, one row per value." }, "metric": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "count" ] } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "errorRate" ] } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "cacheHitRate" ] } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "sum" ] }, "field": { "type": "string", "enum": [ "duration", "cost", "tokens" ] } }, "required": [ "kind", "field" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "min" ] }, "field": { "type": "string", "enum": [ "duration", "cost", "tokens" ] } }, "required": [ "kind", "field" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "max" ] }, "field": { "type": "string", "enum": [ "duration", "cost", "tokens" ] } }, "required": [ "kind", "field" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "avg" ] }, "field": { "type": "string", "enum": [ "duration", "cost", "tokens" ] } }, "required": [ "kind", "field" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "median" ] }, "field": { "type": "string", "enum": [ "duration", "cost", "tokens" ] } }, "required": [ "kind", "field" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "percentile" ] }, "field": { "type": "string", "enum": [ "duration", "cost", "tokens" ] }, "p": { "type": "number", "minimum": 1, "maximum": 99 } }, "required": [ "kind", "field", "p" ] } ], "description": "The metric: `count`, `errorRate`, `cacheHitRate`, `{sum|min|max|avg|median}` over `duration`/`cost`/`tokens`, or `{kind:'percentile',field,p}` for an arbitrary percentile (`p` in [1,99]; e.g. `p:95`)." }, "timeBucket": { "type": "object", "properties": { "unit": { "type": "string", "enum": [ "hour", "day", "week" ], "description": "Bucket granularity." }, "size": { "type": "integer", "exclusiveMinimum": 0, "maximum": 365, "default": 1, "description": "Number of units per bucket (e.g. `2` weeks)." } }, "required": [ "unit" ], "description": "Bucket the metric over time. Omit for a single aggregate." }, "range": { "type": "object", "properties": { "fromIso": { "type": "string", "format": "date-time", "example": "2026-06-23T00:00:00Z", "description": "Inclusive lower bound (ISO-8601)." }, "toIso": { "type": "string", "format": "date-time", "example": "2026-06-30T00:00:00Z", "description": "Exclusive upper bound (ISO-8601). Must be after `fromIso`." } }, "required": [ "fromIso", "toIso" ], "description": "The time window." }, "orderBy": { "type": "object", "properties": { "by": { "type": "string", "enum": [ "value", "key" ], "default": "value" }, "direction": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" } }, "default": { "by": "value", "direction": "desc" }, "description": "Sort for breakdown results. Defaults to value-desc." }, "limit": { "type": "integer", "exclusiveMinimum": 0, "maximum": 500, "default": 50, "description": "Maximum rows returned. Defaults to 50; max 500." }, "filters": { "allOf": [ { "$ref": "#/components/schemas/FilterSet" }, { "description": "Structured filter set applied to the stream (same DSL as `listTraces`)." } ] } }, "required": [ "stream", "metric", "range" ], "additionalProperties": false }, { "type": "object", "properties": { "stream": { "type": "string", "enum": [ "sessions" ] }, "query": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Semantic search query, combined with `filters` via AND. Ranks/filters by relevance." }, "breakdown": { "type": "string", "enum": [ "model", "provider", "service", "tool", "tag", "userId", "status" ], "description": "Dimension to group by, one row per value." }, "metric": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "count" ] } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "errorRate" ] } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "cacheHitRate" ] } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "sum" ] }, "field": { "type": "string", "enum": [ "duration", "cost", "tokens" ] } }, "required": [ "kind", "field" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "min" ] }, "field": { "type": "string", "enum": [ "duration", "cost", "tokens" ] } }, "required": [ "kind", "field" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "max" ] }, "field": { "type": "string", "enum": [ "duration", "cost", "tokens" ] } }, "required": [ "kind", "field" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "avg" ] }, "field": { "type": "string", "enum": [ "duration", "cost", "tokens" ] } }, "required": [ "kind", "field" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "median" ] }, "field": { "type": "string", "enum": [ "duration", "cost", "tokens" ] } }, "required": [ "kind", "field" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "percentile" ] }, "field": { "type": "string", "enum": [ "duration", "cost", "tokens" ] }, "p": { "type": "number", "minimum": 1, "maximum": 99 } }, "required": [ "kind", "field", "p" ] } ], "description": "The metric: `count`, `errorRate`, `cacheHitRate`, `{sum|min|max|avg|median}` over `duration`/`cost`/`tokens`, or `{kind:'percentile',field,p}` for an arbitrary percentile (`p` in [1,99]; e.g. `p:95`)." }, "timeBucket": { "type": "object", "properties": { "unit": { "type": "string", "enum": [ "hour", "day", "week" ], "description": "Bucket granularity." }, "size": { "type": "integer", "exclusiveMinimum": 0, "maximum": 365, "default": 1, "description": "Number of units per bucket (e.g. `2` weeks)." } }, "required": [ "unit" ], "description": "Bucket the metric over time. Omit for a single aggregate." }, "range": { "type": "object", "properties": { "fromIso": { "type": "string", "format": "date-time", "example": "2026-06-23T00:00:00Z", "description": "Inclusive lower bound (ISO-8601)." }, "toIso": { "type": "string", "format": "date-time", "example": "2026-06-30T00:00:00Z", "description": "Exclusive upper bound (ISO-8601). Must be after `fromIso`." } }, "required": [ "fromIso", "toIso" ], "description": "The time window." }, "orderBy": { "type": "object", "properties": { "by": { "type": "string", "enum": [ "value", "key" ], "default": "value" }, "direction": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" } }, "default": { "by": "value", "direction": "desc" }, "description": "Sort for breakdown results. Defaults to value-desc." }, "limit": { "type": "integer", "exclusiveMinimum": 0, "maximum": 500, "default": 50, "description": "Maximum rows returned. Defaults to 50; max 500." }, "filters": { "allOf": [ { "$ref": "#/components/schemas/FilterSet" }, { "description": "Structured filter set applied to the stream (same DSL as `listTraces`)." } ] } }, "required": [ "stream", "metric", "range" ], "additionalProperties": false }, { "type": "object", "properties": { "stream": { "type": "string", "enum": [ "spans" ] }, "breakdown": { "type": "string", "enum": [ "model", "provider", "service", "tool", "tag", "operation", "status" ], "description": "Dimension to group by, one row per value." }, "metric": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "count" ] } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "errorRate" ] } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "cacheHitRate" ] } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "sum" ] }, "field": { "type": "string", "enum": [ "duration", "cost", "tokens" ] } }, "required": [ "kind", "field" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "min" ] }, "field": { "type": "string", "enum": [ "duration", "cost", "tokens" ] } }, "required": [ "kind", "field" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "max" ] }, "field": { "type": "string", "enum": [ "duration", "cost", "tokens" ] } }, "required": [ "kind", "field" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "avg" ] }, "field": { "type": "string", "enum": [ "duration", "cost", "tokens" ] } }, "required": [ "kind", "field" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "median" ] }, "field": { "type": "string", "enum": [ "duration", "cost", "tokens" ] } }, "required": [ "kind", "field" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "percentile" ] }, "field": { "type": "string", "enum": [ "duration", "cost", "tokens" ] }, "p": { "type": "number", "minimum": 1, "maximum": 99 } }, "required": [ "kind", "field", "p" ] } ], "description": "The metric: `count`, `errorRate`, `cacheHitRate`, `{sum|min|max|avg|median}` over `duration`/`cost`/`tokens`, or `{kind:'percentile',field,p}` for an arbitrary percentile (`p` in [1,99]; e.g. `p:95`)." }, "timeBucket": { "type": "object", "properties": { "unit": { "type": "string", "enum": [ "hour", "day", "week" ], "description": "Bucket granularity." }, "size": { "type": "integer", "exclusiveMinimum": 0, "maximum": 365, "default": 1, "description": "Number of units per bucket (e.g. `2` weeks)." } }, "required": [ "unit" ], "description": "Bucket the metric over time. Omit for a single aggregate." }, "range": { "type": "object", "properties": { "fromIso": { "type": "string", "format": "date-time", "example": "2026-06-23T00:00:00Z", "description": "Inclusive lower bound (ISO-8601)." }, "toIso": { "type": "string", "format": "date-time", "example": "2026-06-30T00:00:00Z", "description": "Exclusive upper bound (ISO-8601). Must be after `fromIso`." } }, "required": [ "fromIso", "toIso" ], "description": "The time window." }, "orderBy": { "type": "object", "properties": { "by": { "type": "string", "enum": [ "value", "key" ], "default": "value" }, "direction": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" } }, "default": { "by": "value", "direction": "desc" }, "description": "Sort for breakdown results. Defaults to value-desc." }, "limit": { "type": "integer", "exclusiveMinimum": 0, "maximum": 500, "default": 50, "description": "Maximum rows returned. Defaults to 50; max 500." }, "filters": { "$ref": "#/components/schemas/SpanRowFilterSet" } }, "required": [ "stream", "metric", "range" ], "additionalProperties": false }, { "type": "object", "properties": { "stream": { "type": "string", "enum": [ "scores" ], "description": "Scored occurrences. A signal is scores carrying a `signalId` — analyze one signal via `stream: \"scores\"` filtered by `score.signalId` (or broken down by `signalId`)." }, "breakdown": { "type": "string", "enum": [ "signalId", "source", "model", "provider", "service", "tool", "tag" ], "description": "Dimension to group by: `signalId`/`source` (direct) or a trace dim (`model`…`tag`)." }, "metric": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "count" ] } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "passRate" ] } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "errorRate" ] } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "avg" ] }, "field": { "type": "string", "enum": [ "value" ] } }, "required": [ "kind", "field" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "min" ] }, "field": { "type": "string", "enum": [ "value" ] } }, "required": [ "kind", "field" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "max" ] }, "field": { "type": "string", "enum": [ "value" ] } }, "required": [ "kind", "field" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "median" ] }, "field": { "type": "string", "enum": [ "value" ] } }, "required": [ "kind", "field" ] } ], "description": "The metric: `count`, `passRate`, `errorRate`, or `{avg|min|max|median}` of the 0–1 score `value`." }, "timeBucket": { "type": "object", "properties": { "unit": { "type": "string", "enum": [ "hour", "day", "week" ], "description": "Bucket granularity." }, "size": { "type": "integer", "exclusiveMinimum": 0, "maximum": 365, "default": 1, "description": "Number of units per bucket (e.g. `2` weeks)." } }, "required": [ "unit" ], "description": "Bucket the metric over time. Omit for a single aggregate." }, "range": { "type": "object", "properties": { "fromIso": { "type": "string", "format": "date-time", "example": "2026-06-23T00:00:00Z", "description": "Inclusive lower bound (ISO-8601)." }, "toIso": { "type": "string", "format": "date-time", "example": "2026-06-30T00:00:00Z", "description": "Exclusive upper bound (ISO-8601). Must be after `fromIso`." } }, "required": [ "fromIso", "toIso" ], "description": "The time window." }, "orderBy": { "type": "object", "properties": { "by": { "type": "string", "enum": [ "value", "key" ], "default": "value" }, "direction": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" } }, "default": { "by": "value", "direction": "desc" }, "description": "Sort for breakdown results. Defaults to value-desc." }, "limit": { "type": "integer", "exclusiveMinimum": 0, "maximum": 500, "default": 50, "description": "Maximum rows returned. Defaults to 50; max 500." }, "filters": { "allOf": [ { "$ref": "#/components/schemas/FilterSet" }, { "description": "Structured filter set applied to the stream (same DSL as `listTraces`)." } ] } }, "required": [ "stream", "metric", "range" ], "additionalProperties": false }, { "type": "object", "properties": { "stream": { "type": "string", "enum": [ "behaviors" ], "description": "Taxonomy observations — behavior instances clustered from session moments." }, "breakdown": { "type": "string", "enum": [ "cluster", "session", "method" ], "description": "Dimension to group by: `cluster`, `session`, or `method`." }, "metric": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "count" ] } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "avg" ] }, "field": { "type": "string", "enum": [ "confidence" ] } }, "required": [ "kind", "field" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "min" ] }, "field": { "type": "string", "enum": [ "confidence" ] } }, "required": [ "kind", "field" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "max" ] }, "field": { "type": "string", "enum": [ "confidence" ] } }, "required": [ "kind", "field" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "median" ] }, "field": { "type": "string", "enum": [ "confidence" ] } }, "required": [ "kind", "field" ] } ], "description": "The metric: `count`, or `{avg|min|max|median}` of the 0–1 assignment `confidence`." }, "timeBucket": { "type": "object", "properties": { "unit": { "type": "string", "enum": [ "hour", "day", "week" ], "description": "Bucket granularity." }, "size": { "type": "integer", "exclusiveMinimum": 0, "maximum": 365, "default": 1, "description": "Number of units per bucket (e.g. `2` weeks)." } }, "required": [ "unit" ], "description": "Bucket the metric over time. Omit for a single aggregate." }, "range": { "type": "object", "properties": { "fromIso": { "type": "string", "format": "date-time", "example": "2026-06-23T00:00:00Z", "description": "Inclusive lower bound (ISO-8601)." }, "toIso": { "type": "string", "format": "date-time", "example": "2026-06-30T00:00:00Z", "description": "Exclusive upper bound (ISO-8601). Must be after `fromIso`." } }, "required": [ "fromIso", "toIso" ], "description": "The time window." }, "orderBy": { "type": "object", "properties": { "by": { "type": "string", "enum": [ "value", "key" ], "default": "value" }, "direction": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" } }, "default": { "by": "value", "direction": "desc" }, "description": "Sort for breakdown results. Defaults to value-desc." }, "limit": { "type": "integer", "exclusiveMinimum": 0, "maximum": 500, "default": 50, "description": "Maximum rows returned. Defaults to 50; max 500." }, "filters": { "allOf": [ { "$ref": "#/components/schemas/FilterSet" }, { "description": "Structured filter set applied to the stream (same DSL as `listTraces`)." } ] } }, "required": [ "stream", "metric", "range" ], "additionalProperties": false }, { "type": "object", "properties": { "stream": { "type": "string", "enum": [ "moments" ], "description": "Semantic-moment labels — kind/actor-tagged moments detected within a session." }, "breakdown": { "type": "string", "enum": [ "kind", "actor", "session" ], "description": "Dimension to group by: `kind`, `actor`, or `session`." }, "metric": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "count" ] } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "avg" ] }, "field": { "type": "string", "enum": [ "confidence", "coherence" ] } }, "required": [ "kind", "field" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "min" ] }, "field": { "type": "string", "enum": [ "confidence", "coherence" ] } }, "required": [ "kind", "field" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "max" ] }, "field": { "type": "string", "enum": [ "confidence", "coherence" ] } }, "required": [ "kind", "field" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "median" ] }, "field": { "type": "string", "enum": [ "confidence", "coherence" ] } }, "required": [ "kind", "field" ] } ], "description": "The metric: `count`, or `{avg|min|max|median}` of the 0–1 label `confidence` or moment `coherence`." }, "timeBucket": { "type": "object", "properties": { "unit": { "type": "string", "enum": [ "hour", "day", "week" ], "description": "Bucket granularity." }, "size": { "type": "integer", "exclusiveMinimum": 0, "maximum": 365, "default": 1, "description": "Number of units per bucket (e.g. `2` weeks)." } }, "required": [ "unit" ], "description": "Bucket the metric over time. Omit for a single aggregate." }, "range": { "type": "object", "properties": { "fromIso": { "type": "string", "format": "date-time", "example": "2026-06-23T00:00:00Z", "description": "Inclusive lower bound (ISO-8601)." }, "toIso": { "type": "string", "format": "date-time", "example": "2026-06-30T00:00:00Z", "description": "Exclusive upper bound (ISO-8601). Must be after `fromIso`." } }, "required": [ "fromIso", "toIso" ], "description": "The time window." }, "orderBy": { "type": "object", "properties": { "by": { "type": "string", "enum": [ "value", "key" ], "default": "value" }, "direction": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" } }, "default": { "by": "value", "direction": "desc" }, "description": "Sort for breakdown results. Defaults to value-desc." }, "limit": { "type": "integer", "exclusiveMinimum": 0, "maximum": 500, "default": 50, "description": "Maximum rows returned. Defaults to 50; max 500." }, "filters": { "allOf": [ { "$ref": "#/components/schemas/FilterSet" }, { "description": "Structured filter set applied to the stream (same DSL as `listTraces`)." } ] } }, "required": [ "stream", "metric", "range" ], "additionalProperties": false } ] }, "SpanRowFilterSet": { "type": "object", "additionalProperties": { "type": "array", "items": { "$ref": "#/components/schemas/FilterCondition" } }, "description": "Structured filter set over span row fields. `gtePercentile` is not supported — use absolute thresholds or a percentile metric." }, "QuerySpans": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Span" }, "description": "Matching spans across traces, newest first. Rows exclude per-message LLM content — use a span point-lookup for the payload." }, "nextCursor": { "type": [ "string", "null" ], "description": "Cursor for the next page, or `null` when there are no more spans." }, "hasMore": { "type": "boolean", "description": "Whether more spans match beyond this page." } }, "required": [ "items", "nextCursor", "hasMore" ] }, "QuerySpansBody": { "type": "object", "properties": { "filters": { "allOf": [ { "$ref": "#/components/schemas/SpanRowFilterSet" }, { "description": "Row-local span filter set (same DSL as `listTraces`) over span fields — `operation`, `toolName`, `model`, `provider`, `sessionId`, `traceId`, `tags`, `status` (`error`/`ok`/`unset`), `duration`, `cost`, `tokensInput`/`tokensOutput`. `gtePercentile` is not supported — use absolute thresholds or a percentile metric." } ] }, "orderBy": { "type": "object", "properties": { "field": { "type": "string", "enum": [ "startTime", "duration", "cost" ], "default": "startTime", "description": "Sort key." }, "direction": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc", "description": "Sort direction." } }, "description": "Sort order. Defaults to newest first (`startTime` desc); use `duration`/`cost` desc for top-N slowest/costliest." }, "range": { "type": "object", "properties": { "fromIso": { "type": "string", "format": "date-time", "example": "2026-06-23T00:00:00Z", "description": "Inclusive lower bound (ISO-8601)." }, "toIso": { "type": "string", "format": "date-time", "example": "2026-06-30T00:00:00Z", "description": "Upper bound (ISO-8601). Must be after `fromIso`." } }, "required": [ "fromIso", "toIso" ], "description": "Restrict to spans whose `startTime` falls in this window." }, "cursor": { "type": "string", "description": "Opaque cursor from 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." } } }, "PaginatedExperiments": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ExperimentListItem" }, "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" ] }, "ExperimentListItem": { "type": "object", "properties": { "id": { "type": "string", "minLength": 24, "maxLength": 24, "description": "Stable experiment identifier." }, "organizationId": { "type": "string", "minLength": 24, "maxLength": 24, "description": "Organization that owns this experiment." }, "projectId": { "type": "string", "minLength": 24, "maxLength": 24, "description": "Project this experiment 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." }, "variants": { "type": "array", "items": { "$ref": "#/components/schemas/ExperimentVariant" }, "description": "Ordered variants. Exactly one carries the baseline flag when the list is non-empty." }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp of creation." }, "updatedAt": { "type": "string", "description": "ISO-8601 timestamp of the last update." }, "variantCount": { "type": "integer", "description": "Number of variants in the experiment." }, "sessionsDistinct": { "type": "integer", "description": "Distinct sessions across the union of every variant's population (a session in several variants counts once)." }, "usersDistinct": { "type": "integer", "description": "Distinct users across the union of every variant's population (a user in several variants counts once)." } }, "required": [ "id", "organizationId", "projectId", "slug", "name", "description", "variants", "createdAt", "updatedAt", "variantCount", "sessionsDistinct", "usersDistinct" ] }, "ExperimentVariant": { "type": "object", "properties": { "id": { "type": "string", "minLength": 24, "maxLength": 24, "description": "Stable variant identifier, unique within the experiment." }, "name": { "type": "string", "description": "Human-readable variant name (e.g. \"Variant A\"). Unique within the experiment." }, "baseline": { "type": "boolean", "description": "`true` for the single baseline variant that every other variant is compared against." }, "filterSet": { "allOf": [ { "$ref": "#/components/schemas/FilterSet" }, { "description": "Session filters selecting this variant's population." } ] }, "query": { "type": [ "string", "null" ], "description": "Free-text / semantic search applied to the population, or `null`." }, "timeRange": { "$ref": "#/components/schemas/VariantTimeRange" } }, "required": [ "id", "name", "baseline", "filterSet", "query", "timeRange" ] }, "VariantTimeRange": { "oneOf": [ { "$ref": "#/components/schemas/RelativeVariantTimeRange" }, { "$ref": "#/components/schemas/AbsoluteVariantTimeRange" }, { "type": "null" } ], "description": "Time window the variant is measured over. `null` uses the default last-30-days window." }, "RelativeVariantTimeRange": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "relative" ], "description": "A live window ending now, spanning the last `seconds`." }, "seconds": { "type": "integer", "exclusiveMinimum": 0, "description": "Length of the live window in seconds (e.g. 2592000 for the last 30 days)." } }, "required": [ "type", "seconds" ] }, "AbsoluteVariantTimeRange": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "absolute" ], "description": "A fixed window between two instants." }, "fromIso": { "type": "string", "description": "ISO-8601 start of the window (inclusive)." }, "toIso": { "type": "string", "description": "ISO-8601 end of the window (inclusive)." } }, "required": [ "type", "fromIso", "toIso" ] }, "Experiment": { "type": "object", "properties": { "id": { "type": "string", "minLength": 24, "maxLength": 24, "description": "Stable experiment identifier." }, "organizationId": { "type": "string", "minLength": 24, "maxLength": 24, "description": "Organization that owns this experiment." }, "projectId": { "type": "string", "minLength": 24, "maxLength": 24, "description": "Project this experiment 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." }, "variants": { "type": "array", "items": { "$ref": "#/components/schemas/ExperimentVariant" }, "description": "Ordered variants. Exactly one carries the baseline flag when the list is non-empty." }, "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", "variants", "createdAt", "updatedAt" ] }, "CreateExperimentBody": { "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." }, "variants": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Existing variant id to preserve. Omit to mint a new variant." }, "name": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Variant name. Unique within the experiment." }, "baseline": { "type": "boolean", "description": "`true` for the baseline variant. Exactly one variant must be the baseline." }, "filterSet": { "allOf": [ { "$ref": "#/components/schemas/FilterSet" }, { "description": "Session filters selecting this variant's population." } ] }, "query": { "type": [ "string", "null" ], "maxLength": 500, "description": "Free-text / semantic search, or `null`." }, "timeRange": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "relative" ] }, "seconds": { "type": "integer", "exclusiveMinimum": 0, "description": "Length of the live window in seconds." } }, "required": [ "type", "seconds" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "absolute" ] }, "fromIso": { "type": "string", "description": "ISO-8601 start of the window (inclusive)." }, "toIso": { "type": "string", "description": "ISO-8601 end of the window (inclusive)." } }, "required": [ "type", "fromIso", "toIso" ] }, { "type": "null" } ], "description": "Time window, or `null` for the default last-30-days window." } }, "required": [ "name", "baseline", "filterSet", "query", "timeRange" ] }, "maxItems": 10, "description": "Variant definitions. Omit to seed two default variants (`Variant A` baseline + `Variant B`); pass `[]` to create an empty experiment." } }, "required": [ "name" ] }, "ExperimentComparison": { "type": "object", "properties": { "experiment": { "allOf": [ { "$ref": "#/components/schemas/Experiment" }, { "description": "The experiment, including its variant definitions." } ] }, "variants": { "type": "array", "items": { "$ref": "#/components/schemas/VariantComparison" }, "description": "One entry per variant, in the experiment's stored variant order. The baseline is the entry whose `baseline` field is `true` — identify it by that flag, never by array position." } }, "required": [ "experiment", "variants" ] }, "VariantComparison": { "type": "object", "properties": { "variantId": { "type": "string", "description": "Id of the variant these metrics belong to." }, "baseline": { "type": "boolean", "description": "`true` when this is the baseline variant; every metric's `delta` is `null`." }, "approximate": { "type": "boolean", "description": "`true` when the variant's query has a semantic component, making its population a best-effort sample." }, "resolvedRange": { "$ref": "#/components/schemas/ResolvedRange" }, "metrics": { "$ref": "#/components/schemas/VariantMetrics" }, "deviatingPopulationKeys": { "type": "array", "items": { "type": "string" }, "description": "Population keys (a subset of `sessions.count` / `sessions.users`) that deviate from the baseline by more than 25%." } }, "required": [ "variantId", "baseline", "approximate", "resolvedRange", "metrics", "deviatingPopulationKeys" ] }, "ResolvedRange": { "type": "object", "properties": { "fromIso": { "type": "string", "description": "ISO-8601 start of the resolved window." }, "toIso": { "type": "string", "description": "ISO-8601 end of the resolved window." } }, "required": [ "fromIso", "toIso" ], "description": "The absolute window the metrics were computed over." }, "VariantMetrics": { "type": "object", "properties": { "sessions": { "$ref": "#/components/schemas/ExperimentSessionsMetrics" }, "users": { "$ref": "#/components/schemas/ExperimentUsersMetrics" }, "tools": { "$ref": "#/components/schemas/ExperimentToolsMetrics" }, "signals": { "$ref": "#/components/schemas/ExperimentSignalsMetrics" }, "behaviours": { "$ref": "#/components/schemas/ExperimentBehavioursMetrics" } }, "required": [ "sessions", "users", "tools", "signals", "behaviours" ], "description": "Population-scoped metrics grouped by entity. Each metric is a `{ value, delta }` pair; `delta` is the change vs the baseline (`null` on the baseline itself). `tools`, `signals`, and `behaviours` also carry a `top` ranked list." }, "ExperimentSessionsMetrics": { "type": "object", "properties": { "count": { "type": "object", "properties": { "value": { "type": [ "number", "null" ], "description": "Value in the metric's unit; `null` when empty or not computable." }, "delta": { "$ref": "#/components/schemas/MetricDelta" } }, "required": [ "value", "delta" ], "description": "Number of sessions in the variant's population — count." }, "users": { "type": "object", "properties": { "value": { "type": [ "number", "null" ], "description": "Value in the metric's unit; `null` when empty or not computable." }, "delta": { "$ref": "#/components/schemas/MetricDelta" } }, "required": [ "value", "delta" ], "description": "Distinct users across the variant's sessions — count." }, "cost_total": { "type": "object", "properties": { "value": { "type": [ "number", "null" ], "description": "Value in the metric's unit; `null` when empty or not computable." }, "delta": { "$ref": "#/components/schemas/MetricDelta" } }, "required": [ "value", "delta" ], "description": "Total model cost across the variant's sessions — USD; lower is better." }, "tokens_total": { "type": "object", "properties": { "value": { "type": [ "number", "null" ], "description": "Value in the metric's unit; `null` when empty or not computable." }, "delta": { "$ref": "#/components/schemas/MetricDelta" } }, "required": [ "value", "delta" ], "description": "Total tokens across the variant's sessions — tokens." }, "error_rate": { "type": "object", "properties": { "value": { "type": [ "number", "null" ], "description": "Value in the metric's unit; `null` when empty or not computable." }, "delta": { "$ref": "#/components/schemas/MetricDelta" } }, "required": [ "value", "delta" ], "description": "Fraction of sessions with at least one error — fraction (0–1); lower is better." }, "cache_hit_rate": { "type": "object", "properties": { "value": { "type": [ "number", "null" ], "description": "Value in the metric's unit; `null` when empty or not computable." }, "delta": { "$ref": "#/components/schemas/MetricDelta" } }, "required": [ "value", "delta" ], "description": "Fraction of input tokens served from cache — fraction (0–1); higher is better." }, "duration_median": { "type": "object", "properties": { "value": { "type": [ "number", "null" ], "description": "Value in the metric's unit; `null` when empty or not computable." }, "delta": { "$ref": "#/components/schemas/MetricDelta" } }, "required": [ "value", "delta" ], "description": "Median session duration — seconds; lower is better." }, "duration_p90": { "type": "object", "properties": { "value": { "type": [ "number", "null" ], "description": "Value in the metric's unit; `null` when empty or not computable." }, "delta": { "$ref": "#/components/schemas/MetricDelta" } }, "required": [ "value", "delta" ], "description": "90th-percentile session duration — seconds; lower is better." }, "duration_p95": { "type": "object", "properties": { "value": { "type": [ "number", "null" ], "description": "Value in the metric's unit; `null` when empty or not computable." }, "delta": { "$ref": "#/components/schemas/MetricDelta" } }, "required": [ "value", "delta" ], "description": "95th-percentile session duration — seconds; lower is better." }, "cost_avg": { "type": "object", "properties": { "value": { "type": [ "number", "null" ], "description": "Value in the metric's unit; `null` when empty or not computable." }, "delta": { "$ref": "#/components/schemas/MetricDelta" } }, "required": [ "value", "delta" ], "description": "Average model cost per session — USD; lower is better." }, "tokens_avg": { "type": "object", "properties": { "value": { "type": [ "number", "null" ], "description": "Value in the metric's unit; `null` when empty or not computable." }, "delta": { "$ref": "#/components/schemas/MetricDelta" } }, "required": [ "value", "delta" ], "description": "Average tokens per session — tokens." }, "ttft_median": { "type": "object", "properties": { "value": { "type": [ "number", "null" ], "description": "Value in the metric's unit; `null` when empty or not computable." }, "delta": { "$ref": "#/components/schemas/MetricDelta" } }, "required": [ "value", "delta" ], "description": "Median time to first token across sessions — seconds; lower is better." }, "spans_avg": { "type": "object", "properties": { "value": { "type": [ "number", "null" ], "description": "Value in the metric's unit; `null` when empty or not computable." }, "delta": { "$ref": "#/components/schemas/MetricDelta" } }, "required": [ "value", "delta" ], "description": "Average spans per session — count." }, "traces_avg": { "type": "object", "properties": { "value": { "type": [ "number", "null" ], "description": "Value in the metric's unit; `null` when empty or not computable." }, "delta": { "$ref": "#/components/schemas/MetricDelta" } }, "required": [ "value", "delta" ], "description": "Average traces per session — count." } }, "required": [ "count", "users", "cost_total", "tokens_total", "error_rate", "cache_hit_rate", "duration_median", "duration_p90", "duration_p95", "cost_avg", "tokens_avg", "ttft_median", "spans_avg", "traces_avg" ] }, "MetricDelta": { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "up-from-zero" ] }, { "type": "null" } ], "description": "Change vs the baseline: a signed fraction `(value - baseline) / baseline`, `\"up-from-zero\"` for an unbounded increase from a zero baseline, or `null` when incomparable or on the baseline variant itself." }, "ExperimentUsersMetrics": { "type": "object", "properties": { "distinct": { "type": "object", "properties": { "value": { "type": [ "number", "null" ], "description": "Value in the metric's unit; `null` when empty or not computable." }, "delta": { "$ref": "#/components/schemas/MetricDelta" } }, "required": [ "value", "delta" ], "description": "Distinct users in the variant's population — count." }, "sessions_per_user": { "type": "object", "properties": { "value": { "type": [ "number", "null" ], "description": "Value in the metric's unit; `null` when empty or not computable." }, "delta": { "$ref": "#/components/schemas/MetricDelta" } }, "required": [ "value", "delta" ], "description": "Average sessions per user — count." }, "traces_per_user": { "type": "object", "properties": { "value": { "type": [ "number", "null" ], "description": "Value in the metric's unit; `null` when empty or not computable." }, "delta": { "$ref": "#/components/schemas/MetricDelta" } }, "required": [ "value", "delta" ], "description": "Average traces per user — count." }, "cost_avg": { "type": "object", "properties": { "value": { "type": [ "number", "null" ], "description": "Value in the metric's unit; `null` when empty or not computable." }, "delta": { "$ref": "#/components/schemas/MetricDelta" } }, "required": [ "value", "delta" ], "description": "Average model cost per user — USD; lower is better." }, "duration_median": { "type": "object", "properties": { "value": { "type": [ "number", "null" ], "description": "Value in the metric's unit; `null` when empty or not computable." }, "delta": { "$ref": "#/components/schemas/MetricDelta" } }, "required": [ "value", "delta" ], "description": "Median total session time per user — seconds; lower is better." }, "duration_p90": { "type": "object", "properties": { "value": { "type": [ "number", "null" ], "description": "Value in the metric's unit; `null` when empty or not computable." }, "delta": { "$ref": "#/components/schemas/MetricDelta" } }, "required": [ "value", "delta" ], "description": "90th-percentile total session time per user — seconds; lower is better." }, "duration_p95": { "type": "object", "properties": { "value": { "type": [ "number", "null" ], "description": "Value in the metric's unit; `null` when empty or not computable." }, "delta": { "$ref": "#/components/schemas/MetricDelta" } }, "required": [ "value", "delta" ], "description": "95th-percentile total session time per user — seconds; lower is better." }, "error_session_rate": { "type": "object", "properties": { "value": { "type": [ "number", "null" ], "description": "Value in the metric's unit; `null` when empty or not computable." }, "delta": { "$ref": "#/components/schemas/MetricDelta" } }, "required": [ "value", "delta" ], "description": "Average fraction of a user's sessions that have an error — fraction (0–1); lower is better." } }, "required": [ "distinct", "sessions_per_user", "traces_per_user", "cost_avg", "duration_median", "duration_p90", "duration_p95", "error_session_rate" ] }, "ExperimentToolsMetrics": { "type": "object", "properties": { "calls": { "type": "object", "properties": { "value": { "type": [ "number", "null" ], "description": "Value in the metric's unit; `null` when empty or not computable." }, "delta": { "$ref": "#/components/schemas/MetricDelta" } }, "required": [ "value", "delta" ], "description": "Total tool calls across the variant's sessions — count." }, "distinct": { "type": "object", "properties": { "value": { "type": [ "number", "null" ], "description": "Value in the metric's unit; `null` when empty or not computable." }, "delta": { "$ref": "#/components/schemas/MetricDelta" } }, "required": [ "value", "delta" ], "description": "Distinct tools called — count." }, "sessions_with_tools_rate": { "type": "object", "properties": { "value": { "type": [ "number", "null" ], "description": "Value in the metric's unit; `null` when empty or not computable." }, "delta": { "$ref": "#/components/schemas/MetricDelta" } }, "required": [ "value", "delta" ], "description": "Fraction of sessions that call at least one tool — fraction (0–1)." }, "error_rate": { "type": "object", "properties": { "value": { "type": [ "number", "null" ], "description": "Value in the metric's unit; `null` when empty or not computable." }, "delta": { "$ref": "#/components/schemas/MetricDelta" } }, "required": [ "value", "delta" ], "description": "Fraction of tool calls that error — fraction (0–1); lower is better." }, "duration_p50": { "type": "object", "properties": { "value": { "type": [ "number", "null" ], "description": "Value in the metric's unit; `null` when empty or not computable." }, "delta": { "$ref": "#/components/schemas/MetricDelta" } }, "required": [ "value", "delta" ], "description": "Median tool-call duration — seconds; lower is better." }, "duration_p90": { "type": "object", "properties": { "value": { "type": [ "number", "null" ], "description": "Value in the metric's unit; `null` when empty or not computable." }, "delta": { "$ref": "#/components/schemas/MetricDelta" } }, "required": [ "value", "delta" ], "description": "90th-percentile tool-call duration — seconds; lower is better." }, "duration_p95": { "type": "object", "properties": { "value": { "type": [ "number", "null" ], "description": "Value in the metric's unit; `null` when empty or not computable." }, "delta": { "$ref": "#/components/schemas/MetricDelta" } }, "required": [ "value", "delta" ], "description": "95th-percentile tool-call duration — seconds; lower is better." }, "top": { "type": "array", "items": { "$ref": "#/components/schemas/ExperimentTopListItem" }, "description": "Top tools by call count." } }, "required": [ "calls", "distinct", "sessions_with_tools_rate", "error_rate", "duration_p50", "duration_p90", "duration_p95", "top" ] }, "ExperimentTopListItem": { "type": "object", "properties": { "key": { "type": "string", "description": "Stable identity: tool name, signal slug, or cluster id." }, "label": { "type": "string", "description": "Human-readable label (resolved name; falls back to `key` when unresolved)." }, "value": { "type": "number", "description": "Ranking value: tool calls / signal occurrences / behaviour observations." } }, "required": [ "key", "label", "value" ] }, "ExperimentSignalsMetrics": { "type": "object", "properties": { "distinct": { "type": "object", "properties": { "value": { "type": [ "number", "null" ], "description": "Value in the metric's unit; `null` when empty or not computable." }, "delta": { "$ref": "#/components/schemas/MetricDelta" } }, "required": [ "value", "delta" ], "description": "Distinct signals raised on the variant's sessions — count; lower is better." }, "occurrences": { "type": "object", "properties": { "value": { "type": [ "number", "null" ], "description": "Value in the metric's unit; `null` when empty or not computable." }, "delta": { "$ref": "#/components/schemas/MetricDelta" } }, "required": [ "value", "delta" ], "description": "Total signal occurrences — count; lower is better." }, "affected_sessions_rate": { "type": "object", "properties": { "value": { "type": [ "number", "null" ], "description": "Value in the metric's unit; `null` when empty or not computable." }, "delta": { "$ref": "#/components/schemas/MetricDelta" } }, "required": [ "value", "delta" ], "description": "Fraction of sessions with at least one signal — fraction (0–1); lower is better." }, "affected_traces_rate": { "type": "object", "properties": { "value": { "type": [ "number", "null" ], "description": "Value in the metric's unit; `null` when empty or not computable." }, "delta": { "$ref": "#/components/schemas/MetricDelta" } }, "required": [ "value", "delta" ], "description": "Fraction of traces with at least one signal — fraction (0–1); lower is better." }, "affected_users": { "type": "object", "properties": { "value": { "type": [ "number", "null" ], "description": "Value in the metric's unit; `null` when empty or not computable." }, "delta": { "$ref": "#/components/schemas/MetricDelta" } }, "required": [ "value", "delta" ], "description": "Fraction of users with at least one signal — fraction (0–1); lower is better." }, "cost_impact": { "type": "object", "properties": { "value": { "type": [ "number", "null" ], "description": "Value in the metric's unit; `null` when empty or not computable." }, "delta": { "$ref": "#/components/schemas/MetricDelta" } }, "required": [ "value", "delta" ], "description": "Total model cost of sessions carrying a signal — USD; lower is better." }, "top": { "type": "array", "items": { "$ref": "#/components/schemas/ExperimentTopListItem" }, "description": "Top signals by occurrence count." } }, "required": [ "distinct", "occurrences", "affected_sessions_rate", "affected_traces_rate", "affected_users", "cost_impact", "top" ] }, "ExperimentBehavioursMetrics": { "type": "object", "properties": { "observations": { "type": "object", "properties": { "value": { "type": [ "number", "null" ], "description": "Value in the metric's unit; `null` when empty or not computable." }, "delta": { "$ref": "#/components/schemas/MetricDelta" } }, "required": [ "value", "delta" ], "description": "Total behaviour observations on the variant's sessions — count." }, "distinct_clusters": { "type": "object", "properties": { "value": { "type": [ "number", "null" ], "description": "Value in the metric's unit; `null` when empty or not computable." }, "delta": { "$ref": "#/components/schemas/MetricDelta" } }, "required": [ "value", "delta" ], "description": "Distinct behaviour clusters observed — count." }, "moments": { "type": "object", "properties": { "value": { "type": [ "number", "null" ], "description": "Value in the metric's unit; `null` when empty or not computable." }, "delta": { "$ref": "#/components/schemas/MetricDelta" } }, "required": [ "value", "delta" ], "description": "Semantic moments detected on the variant's sessions — count." }, "top": { "type": "array", "items": { "$ref": "#/components/schemas/ExperimentTopListItem" }, "description": "Top behaviours by observation count." } }, "required": [ "observations", "distinct_clusters", "moments", "top" ] }, "UpdateExperimentBody": { "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." }, "variants": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Existing variant id to preserve. Omit to mint a new variant." }, "name": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Variant name. Unique within the experiment." }, "baseline": { "type": "boolean", "description": "`true` for the baseline variant. Exactly one variant must be the baseline." }, "filterSet": { "allOf": [ { "$ref": "#/components/schemas/FilterSet" }, { "description": "Session filters selecting this variant's population." } ] }, "query": { "type": [ "string", "null" ], "maxLength": 500, "description": "Free-text / semantic search, or `null`." }, "timeRange": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "relative" ] }, "seconds": { "type": "integer", "exclusiveMinimum": 0, "description": "Length of the live window in seconds." } }, "required": [ "type", "seconds" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "absolute" ] }, "fromIso": { "type": "string", "description": "ISO-8601 start of the window (inclusive)." }, "toIso": { "type": "string", "description": "ISO-8601 end of the window (inclusive)." } }, "required": [ "type", "fromIso", "toIso" ] }, { "type": "null" } ], "description": "Time window, or `null` for the default last-30-days window." } }, "required": [ "name", "baseline", "filterSet", "query", "timeRange" ] }, "maxItems": 10, "description": "Full replacement of the variants array. Each variant carries its own `baseline` flag." } } }, "PaginatedSessions": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Session" }, "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" ] }, "Session": { "type": "object", "properties": { "organizationId": { "type": "string", "description": "Organization that owns this session." }, "projectId": { "type": "string", "description": "Project this session belongs to." }, "sessionId": { "type": "string", "description": "Session identifier set by the SDK. Groups the traces of one conversation." }, "traceCount": { "type": "integer", "minimum": 0, "description": "Number of traces in the session." }, "traceIds": { "type": "array", "items": { "type": "string" }, "description": "Identifiers of the traces that make up the session." }, "spanCount": { "type": "integer", "minimum": 0, "description": "Total number of spans across the session's traces." }, "errorCount": { "type": "integer", "minimum": 0, "description": "Number of spans flagged with an error status." }, "startTime": { "type": "string", "description": "ISO-8601 timestamp of the session's earliest span." }, "endTime": { "type": "string", "description": "ISO-8601 timestamp of the session's latest span." }, "lastActivityTime": { "type": "string", "description": "ISO-8601 timestamp of the session's most recent span start." }, "durationNs": { "type": "number", "description": "Active execution time of the session in nanoseconds, not wall-clock." }, "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 the session's LLM spans." }, "tokensOutput": { "type": "number", "description": "Total output tokens across the session's 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)." }, "userId": { "type": [ "string", "null" ], "description": "End-user identifier set by the SDK. `null` when absent." }, "userEmail": { "type": [ "string", "null" ], "description": "End-user email set by the SDK. `null` when absent." }, "simulationId": { "type": [ "string", "null" ], "description": "CUID of the simulation that produced this session. `null` when not a simulation." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Free-form tags attached at ingest time." }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Free-form metadata attached at ingest time." }, "models": { "type": "array", "items": { "type": "string" }, "description": "Model identifiers seen across the session's LLM spans." }, "providers": { "type": "array", "items": { "type": "string" }, "description": "LLM-provider identifiers seen across the session's spans." }, "serviceNames": { "type": "array", "items": { "type": "string" }, "description": "OpenTelemetry `service.name` values seen in the session." }, "agentNames": { "type": "array", "items": { "type": "string" }, "description": "Agent names seen across the session's spans." }, "definedTools": { "type": "array", "items": { "type": "string" }, "description": "Tool names declared available across the session's spans." }, "rootSpanId": { "type": [ "string", "null" ], "description": "Identifier of the session'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." } }, "required": [ "organizationId", "projectId", "sessionId", "traceCount", "traceIds", "spanCount", "errorCount", "startTime", "endTime", "lastActivityTime", "durationNs", "timeToFirstTokenNs", "tokensInput", "tokensOutput", "tokensCacheRead", "tokensCacheCreate", "tokensReasoning", "tokensTotal", "costInputMicrocents", "costOutputMicrocents", "costTotalMicrocents", "userId", "userEmail", "simulationId", "tags", "metadata", "models", "providers", "serviceNames", "agentNames", "definedTools", "rootSpanId", "rootSpanName" ] }, "ListSessionsBody": { "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": [ "lastActivity", "startTime", "duration", "ttft", "cost", "spans", "traceCount" ], "default": "lastActivity", "description": "Field to sort by. Defaults to `lastActivity` (most recently active first)." }, "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 sessions' traces (input and output messages). Combined with `filters` via AND." }, "filters": { "$ref": "#/components/schemas/SessionFilterSet" } } }, "SessionFilterSet": { "type": "object", "additionalProperties": { "type": "array", "items": { "$ref": "#/components/schemas/FilterCondition" } }, "description": "Filter set keyed by session field. Each entry holds an array of conditions ANDed together for that field; field-level groups are ANDed across the set. Valid fields: status, name, traceId, sessionId, simulationId, userId, tags, moments, topics, models, providers, serviceNames, tools, definedTools, duration, ttft, cost, spanCount, errorCount, tokensInput, tokensOutput, cacheHitRate, startTime, endTime; score-derived keys (score.passed, score.errored, score.value, score.source, score.sourceId, score.annotatorId, score.signalId, score.simulationId); and arbitrary metadata via `metadata.`. `moments` filters by conversation moment kind and `topics` by behavior topic id (a topic matches its whole subtree). `startTime`/`endTime` take ISO-8601 values (a session's first span start / last span end). `gtePercentile` is only supported on duration/ttft/cost. Unknown fields are rejected rather than ignored." }, "SessionAnalyticsResponse": { "type": "object", "properties": { "sessions": { "$ref": "#/components/schemas/SessionAnalyticsSessions" }, "traces": { "$ref": "#/components/schemas/SessionAnalyticsTraces" }, "cost": { "$ref": "#/components/schemas/SessionAnalyticsCost" }, "duration": { "$ref": "#/components/schemas/SessionAnalyticsDuration" }, "tokens": { "$ref": "#/components/schemas/SessionAnalyticsTokens" }, "timeToFirstToken": { "$ref": "#/components/schemas/SessionAnalyticsTimeToFirstToken" }, "spans": { "$ref": "#/components/schemas/SessionAnalyticsSpans" } }, "required": [ "sessions", "traces", "cost", "duration", "tokens", "timeToFirstToken", "spans" ] }, "SessionAnalyticsSessions": { "type": "object", "properties": { "total": { "type": "number", "description": "Number of sessions in the range." }, "buckets": { "type": "array", "items": { "$ref": "#/components/schemas/SessionAnalyticsBucket" }, "description": "Number of sessions per bucket." } }, "required": [ "total", "buckets" ] }, "SessionAnalyticsBucket": { "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" ] }, "SessionAnalyticsTraces": { "type": "object", "properties": { "total": { "type": "number", "description": "Number of traces across the range's sessions." }, "buckets": { "type": "array", "items": { "$ref": "#/components/schemas/SessionAnalyticsBucket" }, "description": "Number of traces per bucket." } }, "required": [ "total", "buckets" ] }, "SessionAnalyticsCost": { "type": "object", "properties": { "total": { "type": "number", "description": "Total session cost in USD." }, "buckets": { "type": "array", "items": { "$ref": "#/components/schemas/SessionAnalyticsBucket" }, "description": "Session cost per bucket in USD." } }, "required": [ "total", "buckets" ] }, "SessionAnalyticsDuration": { "type": "object", "properties": { "median": { "type": "number", "description": "Median session duration in seconds." }, "buckets": { "type": "array", "items": { "$ref": "#/components/schemas/SessionAnalyticsBucket" }, "description": "Median session duration per bucket in seconds." } }, "required": [ "median", "buckets" ] }, "SessionAnalyticsTokens": { "type": "object", "properties": { "total": { "type": "number", "description": "Total tokens across all LLM spans." }, "buckets": { "type": "array", "items": { "$ref": "#/components/schemas/SessionAnalyticsBucket" }, "description": "Tokens per bucket across all LLM spans." } }, "required": [ "total", "buckets" ] }, "SessionAnalyticsTimeToFirstToken": { "type": "object", "properties": { "median": { "type": "number", "description": "Median time-to-first-token across LLM spans, in seconds." }, "buckets": { "type": "array", "items": { "$ref": "#/components/schemas/SessionAnalyticsBucket" }, "description": "Median time-to-first-token per bucket, in seconds." } }, "required": [ "median", "buckets" ] }, "SessionAnalyticsSpans": { "type": "object", "properties": { "total": { "type": "number", "description": "Total number of spans." }, "buckets": { "type": "array", "items": { "$ref": "#/components/schemas/SessionAnalyticsBucket" }, "description": "Number of spans per bucket." } }, "required": [ "total", "buckets" ] }, "SessionDetail": { "type": "object", "properties": { "organizationId": { "type": "string", "description": "Organization that owns this session." }, "projectId": { "type": "string", "description": "Project this session belongs to." }, "sessionId": { "type": "string", "description": "Session identifier set by the SDK. Groups the traces of one conversation." }, "traceCount": { "type": "integer", "minimum": 0, "description": "Number of traces in the session." }, "traceIds": { "type": "array", "items": { "type": "string" }, "description": "Identifiers of the traces that make up the session." }, "spanCount": { "type": "integer", "minimum": 0, "description": "Total number of spans across the session's traces." }, "errorCount": { "type": "integer", "minimum": 0, "description": "Number of spans flagged with an error status." }, "startTime": { "type": "string", "description": "ISO-8601 timestamp of the session's earliest span." }, "endTime": { "type": "string", "description": "ISO-8601 timestamp of the session's latest span." }, "lastActivityTime": { "type": "string", "description": "ISO-8601 timestamp of the session's most recent span start." }, "durationNs": { "type": "number", "description": "Active execution time of the session in nanoseconds, not wall-clock." }, "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 the session's LLM spans." }, "tokensOutput": { "type": "number", "description": "Total output tokens across the session's 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)." }, "userId": { "type": [ "string", "null" ], "description": "End-user identifier set by the SDK. `null` when absent." }, "userEmail": { "type": [ "string", "null" ], "description": "End-user email set by the SDK. `null` when absent." }, "simulationId": { "type": [ "string", "null" ], "description": "CUID of the simulation that produced this session. `null` when not a simulation." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Free-form tags attached at ingest time." }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Free-form metadata attached at ingest time." }, "models": { "type": "array", "items": { "type": "string" }, "description": "Model identifiers seen across the session's LLM spans." }, "providers": { "type": "array", "items": { "type": "string" }, "description": "LLM-provider identifiers seen across the session's spans." }, "serviceNames": { "type": "array", "items": { "type": "string" }, "description": "OpenTelemetry `service.name` values seen in the session." }, "agentNames": { "type": "array", "items": { "type": "string" }, "description": "Agent names seen across the session's spans." }, "definedTools": { "type": "array", "items": { "type": "string" }, "description": "Tool names declared available across the session's spans." }, "rootSpanId": { "type": [ "string", "null" ], "description": "Identifier of the session'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." }, "latestTraceId": { "type": [ "string", "null" ], "description": "Identifier of the trace that produced the session's latest output. `null` when no trace produced output." }, "conversation": { "type": "array", "items": { "$ref": "#/components/schemas/GenAIMessage" }, "description": "Conversation of the session, in OpenTelemetry GenAI format: the system instructions, then the messages of the session's latest LLM completion, followed by its generated output." } }, "required": [ "organizationId", "projectId", "sessionId", "traceCount", "traceIds", "spanCount", "errorCount", "startTime", "endTime", "lastActivityTime", "durationNs", "timeToFirstTokenNs", "tokensInput", "tokensOutput", "tokensCacheRead", "tokensCacheCreate", "tokensReasoning", "tokensTotal", "costInputMicrocents", "costOutputMicrocents", "costTotalMicrocents", "userId", "userEmail", "simulationId", "tags", "metadata", "models", "providers", "serviceNames", "agentNames", "definedTools", "rootSpanId", "rootSpanName", "latestTraceId", "conversation" ] }, "SessionSignals": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/SessionSignal" }, "description": "Signals that occurred in the session, ordered by most recent occurrence first." } }, "required": [ "items" ] }, "SessionSignal": { "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` + `new`)." }, "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`." }, "regressedAt": { "type": [ "string", "null" ], "description": "ISO-8601 timestamp at which a new occurrence reopened the resolved signal, or `null`." }, "mutedAt": { "type": [ "string", "null" ], "description": "ISO-8601 timestamp at which notifications were muted, or `null`. Muting only silences notifications; incidents still open." }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp of creation." }, "updatedAt": { "type": "string", "description": "ISO-8601 timestamp of the last update." }, "occurrences": { "type": "integer", "minimum": 0, "description": "Number of occurrences within the session." }, "firstSeenAt": { "type": "string", "description": "ISO-8601 timestamp of the earliest occurrence in the session." }, "lastSeenAt": { "type": "string", "description": "ISO-8601 timestamp of the latest occurrence in the session." }, "traceIds": { "type": "array", "items": { "type": "string" }, "description": "Traces of the session where the signal occurred." } }, "required": [ "id", "organizationId", "projectId", "slug", "name", "description", "source", "states", "resolvedAt", "ignoredAt", "regressedAt", "mutedAt", "createdAt", "updatedAt", "occurrences", "firstSeenAt", "lastSeenAt", "traceIds" ] }, "PaginatedMemoryStores": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/MemoryStore" }, "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" ] }, "MemoryStore": { "type": "object", "properties": { "storeId": { "type": "string", "description": "Store identifier (`gen_ai.memory.store.id`). The empty string is the unattributed bucket." }, "recordCount": { "type": "integer", "minimum": 0, "description": "Number of live (non-deleted) records in the store." }, "tokenCount": { "type": "integer", "minimum": 0, "description": "Total tokens across the store's live record bodies." }, "lastUpdatedAt": { "type": "string", "description": "ISO-8601 timestamp of the store's most recent mutating write." }, "lastReadAt": { "type": [ "string", "null" ], "description": "ISO-8601 timestamp of the store's most recent read. `null` when never read." }, "sessionCount": { "type": "integer", "minimum": 0, "description": "Number of distinct sessions that wrote to the store." }, "userCount": { "type": "integer", "minimum": 0, "description": "Number of distinct end-users who accessed the store." } }, "required": [ "storeId", "recordCount", "tokenCount", "lastUpdatedAt", "lastReadAt", "sessionCount", "userCount" ] }, "MemoryStoreSnapshot": { "type": "object", "properties": { "records": { "type": "array", "items": { "$ref": "#/components/schemas/MemoryStoreRecord" }, "description": "The store's current records (ids plus light metadata), one per live record." } }, "required": [ "records" ] }, "MemoryStoreRecord": { "type": "object", "properties": { "recordId": { "type": "string", "description": "Record identifier (`gen_ai.memory.record.id`); opaque. The empty string is the unnamed record." }, "tokenCount": { "type": "integer", "minimum": 0, "description": "Tokens in the record's current body." }, "lastUpdatedAt": { "type": "string", "description": "ISO-8601 timestamp of the version that produced the current body." } }, "required": [ "recordId", "tokenCount", "lastUpdatedAt" ] }, "MemoryStoreDiff": { "type": "object", "properties": { "storeId": { "type": "string", "description": "Store the diff was computed for." }, "changes": { "type": "array", "items": { "$ref": "#/components/schemas/MemoryStoreChange" }, "description": "Per-record changes between the two points; unchanged records are pruned." }, "tokensAdded": { "type": "integer", "minimum": 0, "description": "Total tokens added across all changed records." }, "tokensRemoved": { "type": "integer", "minimum": 0, "description": "Total tokens removed across all changed records." }, "recordsChanged": { "type": "object", "properties": { "added": { "type": "integer", "minimum": 0, "description": "Number of records added." }, "updated": { "type": "integer", "minimum": 0, "description": "Number of records updated." }, "removed": { "type": "integer", "minimum": 0, "description": "Number of records removed." } }, "required": [ "added", "updated", "removed" ], "description": "Count of changed records per bucket." } }, "required": [ "storeId", "changes", "tokensAdded", "tokensRemoved", "recordsChanged" ] }, "MemoryStoreChange": { "type": "object", "properties": { "recordId": { "type": "string", "description": "Record that changed between the two points." }, "kind": { "type": "string", "enum": [ "added", "updated", "removed" ], "description": "How the record changed: `added` (only at `to`), `removed` (only at `from`), or `updated` (present at both with a different body)." }, "tokensAdded": { "type": "integer", "minimum": 0, "description": "Tokens inserted by this change." }, "tokensRemoved": { "type": "integer", "minimum": 0, "description": "Tokens deleted by this change." }, "degraded": { "type": "boolean", "description": "`true` when a body was unavailable and token counts fall back to record-level estimates." } }, "required": [ "recordId", "kind", "tokensAdded", "tokensRemoved", "degraded" ] }, "MemoryStoreUsers": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/MemoryStoreUser" }, "description": "End-users who accessed the store, most recent access first." } }, "required": [ "items" ] }, "MemoryStoreUser": { "type": "object", "properties": { "userId": { "type": "string", "description": "End-user identifier that accessed the store." }, "lastAccessedAt": { "type": "string", "description": "ISO-8601 timestamp of the user's most recent access (read or write)." } }, "required": [ "userId", "lastAccessedAt" ] }, "MemoryRecordDetail": { "type": "object", "properties": { "body": { "type": [ "string", "null" ], "description": "The record's current body. `null` when the record is deleted or its body was not captured." }, "tokenCount": { "type": "integer", "minimum": 0, "description": "Tokens in the current body." }, "versions": { "type": "array", "items": { "$ref": "#/components/schemas/MemoryRecordVersion" }, "description": "The record's mutating version chain, newest first." } }, "required": [ "body", "tokenCount", "versions" ] }, "MemoryRecordVersion": { "type": "object", "properties": { "changeKind": { "type": "string", "enum": [ "add", "update", "remove", "read", "store_create", "store_delete" ], "description": "Kind of memory operation: `add`/`update`/`remove` (mutations), `read` (retrieval), or `store_create`/`store_delete` (store lifecycle)." }, "tokenCount": { "type": "integer", "minimum": 0, "description": "Tokens in the body produced by this version." }, "tokensAdded": { "type": "integer", "minimum": 0, "description": "Tokens added by this version versus its predecessor." }, "tokensRemoved": { "type": "integer", "minimum": 0, "description": "Tokens removed by this version versus its predecessor." }, "spanId": { "type": "string", "description": "Span that authored this version." }, "traceId": { "type": "string", "description": "Trace the authoring span belongs to." }, "sessionId": { "type": "string", "description": "Session the authoring trace belongs to." }, "userId": { "type": "string", "description": "End-user attributed to the authoring span. Empty when none." }, "endTime": { "type": "string", "description": "ISO-8601 timestamp of the authoring span's end (the version ordering key)." } }, "required": [ "changeKind", "tokenCount", "tokensAdded", "tokensRemoved", "spanId", "traceId", "sessionId", "userId", "endTime" ] }, "MemoryRecordChangeDiff": { "type": "object", "properties": { "changeKind": { "type": "string", "enum": [ "add", "update", "remove", "read", "store_create", "store_delete" ], "description": "Kind of memory operation: `add`/`update`/`remove` (mutations), `read` (retrieval), or `store_create`/`store_delete` (store lifecycle)." }, "beforeBody": { "type": [ "string", "null" ], "description": "The record's body before the change. `null` for the record's first version, a re-create after removal, or when the prior body was not captured." }, "afterBody": { "type": [ "string", "null" ], "description": "The record's body after the change. `null` for a `remove`, or when the body was not captured." }, "degraded": { "type": "boolean", "description": "`true` when a side's body was unavailable, so the diff is incomplete." } }, "required": [ "changeKind", "beforeBody", "afterBody", "degraded" ] }, "MemoryRecordReads": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/MemoryRecordRead" }, "description": "Retrieval events for the record, newest first, capped." } }, "required": [ "items" ] }, "MemoryRecordRead": { "type": "object", "properties": { "spanId": { "type": "string", "description": "Span that performed the read (`search_memory`)." }, "traceId": { "type": "string", "description": "Trace the read span belongs to." }, "sessionId": { "type": "string", "description": "Session the read trace belongs to." }, "userId": { "type": "string", "description": "End-user attributed to the read. Empty when none." }, "queryText": { "type": "string", "description": "The search query text, when captured (opt-in). Empty otherwise." }, "tokenCount": { "type": "integer", "minimum": 0, "description": "Tokens in the record returned by the read." }, "endTime": { "type": "string", "description": "ISO-8601 timestamp of the read span's end." } }, "required": [ "spanId", "traceId", "sessionId", "userId", "queryText", "tokenCount", "endTime" ] }, "MemoryRecordUsers": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/MemoryRecordUser" }, "description": "End-users who accessed the record, most recent access first." } }, "required": [ "items" ] }, "MemoryRecordUser": { "type": "object", "properties": { "userId": { "type": "string", "description": "End-user identifier that accessed the record." }, "readCount": { "type": "integer", "minimum": 0, "description": "Number of reads the user made on the record." }, "writeCount": { "type": "integer", "minimum": 0, "description": "Number of writes the user made to the record." }, "lastAccessedAt": { "type": "string", "description": "ISO-8601 timestamp of the user's most recent access." } }, "required": [ "userId", "readCount", "writeCount", "lastAccessedAt" ] } }, "parameters": {} }, "paths": { "/health": { "get": { "operationId": "health.get", "tags": [ "Health" ], "summary": "Health check", "security": [], "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.", "security": [], "x-fern-ignore": true, "responses": { "200": { "description": "Protected resource metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthProtectedResourceMetadata" } } } } } } }, "/v1/account/bootstrap": { "post": { "operationId": "bootstrapAccount", "tags": [ "Account" ], "x-fern-sdk-group-name": "account", "x-fern-sdk-method-name": "bootstrap", "summary": "Bootstrap a temporary account", "description": "Creates a temporary organization with an API key and a project, and returns a link to claim ownership of it. Requires no authentication.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BootstrapAccountBody" } } } }, "responses": { "201": { "description": "Temporary account created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BootstrapAccountResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/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 its `conversation`: the system instructions and the messages of the trace's last LLM-completion span, in OpenTelemetry GenAI format.", "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/{traceId}/memory": { "get": { "tags": [ "Traces" ], "x-fern-sdk-group-name": "traces", "x-fern-sdk-method-name": "getMemory", "summary": "Get trace memory footprint", "description": "Returns the trace's memory footprint: per-record read, added, and removed token metrics plus totals, scoped to this trace.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "getTraceMemory", "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 memory footprint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionMemorySummary" } } } }, "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}/memory/changes": { "get": { "tags": [ "Traces" ], "x-fern-sdk-group-name": "traces", "x-fern-sdk-method-name": "getMemoryChanges", "summary": "Get trace memory changes", "description": "Returns the memory writes the trace made as per-record before/after diffs, scoped to this trace.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "getTraceMemoryChanges", "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 memory changes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionMemoryChanges" } } } }, "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" } } } }, "429": { "description": "Export rate limit exceeded", "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}/memory": { "get": { "tags": [ "Users" ], "x-fern-sdk-group-name": "users", "x-fern-sdk-method-name": "memoryStores", "summary": "List memory stores an end-user accessed", "description": "Returns the memory stores the end-user accessed (reads and writes both count as access), most recent access first. Capped at the 1000 most recent stores. Each store links to the memory browsing operations under the `memory` group.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "listUserMemoryStores", "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" } ], "responses": { "200": { "description": "Memory stores accessed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserMemoryStores" } } } }, "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`, `affectedSessionsPercent`, `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 signals that are neither resolved nor ignored; `\"archived\"` for resolved or ignored signals. Omit to include both." }, "required": false, "description": "`\"active\"` for signals that are neither resolved nor ignored; `\"archived\"` for resolved or ignored signals. 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" } } } } } }, "post": { "tags": [ "Signals" ], "x-fern-sdk-group-name": "signals", "x-fern-sdk-method-name": "create", "summary": "Create signal", "description": "Creates a user-defined signal with its membership detector — from `settings` (a `judge` LLM detector or a deterministic `rule`), or a raw `script` (advanced). The script is validated at save time (422 on a compile error). Detectors collect forward from creation; there is no historical backfill.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "createSignal", "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/CreateSignalBody" } } } }, "responses": { "201": { "description": "Signal created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSignalResponse" } } } }, "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}": { "patch": { "tags": [ "Signals" ], "x-fern-sdk-group-name": "signals", "x-fern-sdk-method-name": "update", "summary": "Update signal", "description": "Updates a signal's name, description, and evaluation pre-gate `filters`. Filter changes apply forward-only — existing membership is never re-evaluated. The slug is stable.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "updateSignal", "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" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSignalBody" } } } }, "responses": { "200": { "description": "Signal updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSignalResponse" } } } }, "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": [ "Signals" ], "x-fern-sdk-group-name": "signals", "x-fern-sdk-method-name": "delete", "summary": "Delete signal", "description": "Soft-deletes a signal and archives its detector so it stops matching new traces. Existing scores are retained but excluded from reads; the slug becomes reusable.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "deleteSignal", "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 deleted" } } }, "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`, `affectedSessionsPercent`, `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/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, and escalating 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}/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, archiving it and re-enabling its notifications. Unless `keepMonitoring` is `false`, linked evaluations keep running so a new occurrence reopens the signal as regressed.", "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": "Reopens each signal in `signalIds` without marking it as regressed, re-enabling its notifications.", "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, archiving it. Monitoring is stopped and notifications are also muted.", "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": "Returns each signal in `signalIds` to the active list and re-enables its notifications.", "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/mute": { "post": { "tags": [ "Signals" ], "x-fern-sdk-group-name": "signals", "x-fern-sdk-method-name": "mute", "summary": "Mute signals", "description": "Silences notifications for each signal in `signalIds`. Muted signals keep tracking occurrences and opening incidents; only notifications stop.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "muteSignals", "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/unmute": { "post": { "tags": [ "Signals" ], "x-fern-sdk-group-name": "signals", "x-fern-sdk-method-name": "unmute", "summary": "Unmute signals", "description": "Re-enables notifications for each signal in `signalIds`.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "unmuteSignals", "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" } } } }, "429": { "description": "Export rate limit exceeded", "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": "string", "enum": [ "monitor", "signal" ], "description": "Restrict to incidents triggered by this source type: `monitor` or `signal`." }, "required": false, "description": "Restrict to incidents triggered by this source type: `monitor` or `signal`.", "name": "source_type", "in": "query" }, { "schema": { "type": "string", "minLength": 24, "maxLength": 24, "description": "Restrict to incidents tied to one source entity id." }, "required": false, "description": "Restrict to incidents tied to one source entity id.", "name": "source_id", "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/{rowId}": { "patch": { "tags": [ "Datasets" ], "x-fern-sdk-group-name": "datasets", "x-fern-sdk-method-name": "updateRow", "summary": "Update a dataset row", "description": "Partially updates a single row. Only the cells you send are changed; omitted cells keep their current value. Use this to fill in an `expectedOutput` (or any other cell) after rows were imported. Bumps the dataset version.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "updateDatasetRow", "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", "minLength": 1, "description": "Stable row identifier (from `listDatasetRows`)." }, "required": true, "description": "Stable row identifier (from `listDatasetRows`).", "name": "rowId", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateDatasetRowBody" } } } }, "responses": { "200": { "description": "Row updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateDatasetRowResponse" } } } }, "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" } } } }, "429": { "description": "Export rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/datasets/{datasetSlug}/columns": { "get": { "tags": [ "Datasets" ], "x-fern-sdk-group-name": "datasets", "x-fern-sdk-method-name": "listColumns", "summary": "List dataset columns", "description": "Returns the ordered active column schema — the built-in columns plus any custom columns. Pass `includeRemoved=true` to also return soft-removed columns (so they can be restored).", "security": [ { "ApiKeyAuth": [] } ], "operationId": "listDatasetColumns", "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", "enum": [ "true", "false" ], "description": "When `true`, also returns soft-removed columns (each carrying `removed: true`). Defaults to `false`." }, "required": false, "description": "When `true`, also returns soft-removed columns (each carrying `removed: true`). Defaults to `false`.", "name": "includeRemoved", "in": "query" } ], "responses": { "200": { "description": "Column schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasetColumnsList" } } } }, "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": "addColumn", "summary": "Add dataset column", "description": "Adds a custom column. The column starts empty on every row; rows are written only when a cell is filled, so the dataset version does not change.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "addDatasetColumn", "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/AddDatasetColumnBody" } } } }, "responses": { "201": { "description": "Created column", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasetColumn" } } } }, "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}/columns/{identifier}": { "patch": { "tags": [ "Datasets" ], "x-fern-sdk-group-name": "datasets", "x-fern-sdk-method-name": "updateColumn", "summary": "Update dataset column", "description": "Renames a column. Works for both built-in and custom columns.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "updateDatasetColumn", "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", "minLength": 1, "description": "Stable column identifier." }, "required": true, "description": "Stable column identifier.", "name": "identifier", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateDatasetColumnBody" } } } }, "responses": { "200": { "description": "Updated column", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasetColumn" } } } }, "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": "deleteColumn", "summary": "Delete dataset column", "description": "Removes a column (built-in or custom) from the active schema. Its data is preserved and the column can be re-added; this does not change the dataset version.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "deleteDatasetColumn", "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", "minLength": 1, "description": "Stable column identifier." }, "required": true, "description": "Stable column identifier.", "name": "identifier", "in": "path" } ], "responses": { "204": { "description": "Column 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}/datasets/{datasetSlug}/columns/reorder": { "post": { "tags": [ "Datasets" ], "x-fern-sdk-group-name": "datasets", "x-fern-sdk-method-name": "reorderColumns", "summary": "Reorder dataset columns", "description": "Sets the left-to-right order of columns. This is a metadata edit and does not change the dataset version.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "reorderDatasetColumns", "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/ReorderDatasetColumnsBody" } } } }, "responses": { "200": { "description": "Reordered column schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasetColumnsList" } } } }, "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}/columns/{identifier}/restore": { "post": { "tags": [ "Datasets" ], "x-fern-sdk-group-name": "datasets", "x-fern-sdk-method-name": "restoreColumn", "summary": "Restore dataset column", "description": "Restores a soft-removed column (built-in or custom) to the active schema, reconnecting its preserved data. Find removed identifiers via `listDatasetColumns` with `includeRemoved=true`.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "restoreDatasetColumn", "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", "minLength": 1, "description": "Stable column identifier." }, "required": true, "description": "Stable column identifier.", "name": "identifier", "in": "path" } ], "responses": { "200": { "description": "Restored column", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasetColumn" } } } }, "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/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 rule. 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 monitors matching the supplied target type and/or filter subset.", "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 metadata and incident severity. Target, trigger, metric, and conditions are fixed after creation. System monitor edits are restricted.", "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. 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}/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" } } } } } } }, "/v1/projects/{projectSlug}/analytics/query": { "post": { "tags": [ "Analytics" ], "x-fern-sdk-group-name": "analytics", "x-fern-sdk-method-name": "query", "summary": "Run an analytics query", "description": "Compute a metric over a filtered stream (`traces`/`sessions`/`spans`), optionally broken down by a dimension and/or bucketed over time. Returns a tidy series — one point per breakdown value and/or time bucket — suitable for charts and dashboards.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "queryAnalytics", "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/AnalyticsQuery" } } } }, "responses": { "200": { "description": "The analytics series", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsSeries" } } } }, "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}/spans/query": { "post": { "tags": [ "Spans" ], "x-fern-sdk-group-name": "spans", "x-fern-sdk-method-name": "query", "summary": "Query spans across traces", "description": "Returns a cursor-paginated page of spans across all traces in the project matching `filters` (and an optional time `range`). The span-grain, row-level complement to `queryAnalytics` with `stream: \"spans\"` (which returns aggregates): use this to drill from an aggregate into the individual spans behind it — e.g. every failing `search_docs` tool span, or the slowest embedding calls.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "querySpans", "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/QuerySpansBody" } } } }, "responses": { "200": { "description": "Page of spans", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuerySpans" } } } }, "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}/experiments": { "get": { "tags": [ "Experiments" ], "x-fern-sdk-group-name": "experiments", "x-fern-sdk-method-name": "list", "summary": "List experiments", "description": "Returns the project's experiments with cheap summary metrics (variant count, distinct sessions and users across all variant populations). Excludes per-variant comparison metrics — fetch a single experiment for those.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "listExperiments", "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 experiments", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedExperiments" } } } }, "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": [ "Experiments" ], "x-fern-sdk-group-name": "experiments", "x-fern-sdk-method-name": "create", "summary": "Create experiment", "description": "Creates an experiment. The slug is derived from `name`. Omit `variants` to seed two defaults.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "createExperiment", "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/CreateExperimentBody" } } } }, "responses": { "201": { "description": "Experiment created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Experiment" } } } }, "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}/experiments/{experimentSlug}": { "get": { "tags": [ "Experiments" ], "x-fern-sdk-group-name": "experiments", "x-fern-sdk-method-name": "get", "summary": "Get experiment", "description": "Returns a single experiment plus its comparison: per-variant metrics, deltas vs the baseline, and population-deviation flags.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "getExperiment", "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": "Experiment slug (human-readable identifier within the project)." }, "required": true, "description": "Experiment slug (human-readable identifier within the project).", "name": "experimentSlug", "in": "path" } ], "responses": { "200": { "description": "Experiment comparison", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExperimentComparison" } } } }, "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" } } } } } }, "put": { "tags": [ "Experiments" ], "x-fern-sdk-group-name": "experiments", "x-fern-sdk-method-name": "update", "summary": "Update experiment", "description": "Replaces an experiment's mutable fields. `variants`, when supplied, fully replaces the array (each variant carries its own `baseline` flag). Renaming may regenerate the slug.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "updateExperiment", "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": "Experiment slug (human-readable identifier within the project)." }, "required": true, "description": "Experiment slug (human-readable identifier within the project).", "name": "experimentSlug", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateExperimentBody" } } } }, "responses": { "200": { "description": "Updated experiment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Experiment" } } } }, "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": [ "Experiments" ], "x-fern-sdk-group-name": "experiments", "x-fern-sdk-method-name": "delete", "summary": "Delete experiment", "description": "Deletes an experiment. Its slug becomes reusable.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "deleteExperiment", "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": "Experiment slug (human-readable identifier within the project)." }, "required": true, "description": "Experiment slug (human-readable identifier within the project).", "name": "experimentSlug", "in": "path" } ], "responses": { "204": { "description": "Experiment 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}/sessions/list": { "post": { "tags": [ "Sessions" ], "x-fern-sdk-group-name": "sessions", "x-fern-sdk-method-name": "list", "summary": "List project sessions", "description": "Returns a cursor-paginated page of sessions in the project. A session groups the traces of one conversation. Combine `filters` with `query` (free-text semantic search) to narrow the result set. Session list rows exclude per-message LLM content — use `getSession` for the conversation view.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "listSessions", "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/ListSessionsBody" } } } }, "responses": { "200": { "description": "Page of sessions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedSessions" } } } }, "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}/sessions/analytics": { "get": { "tags": [ "Sessions" ], "x-fern-sdk-group-name": "sessions", "x-fern-sdk-method-name": "analytics", "summary": "Get project session analytics", "description": "Returns session 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": "getSessionAnalytics", "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": "Session analytics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionAnalyticsResponse" } } } }, "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}/sessions/{sessionId}": { "get": { "tags": [ "Sessions" ], "x-fern-sdk-group-name": "sessions", "x-fern-sdk-method-name": "get", "summary": "Get project session", "description": "Returns a single session by id, including its `conversation`: the system instructions and the messages of the session's latest LLM completion, in OpenTelemetry GenAI format.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "getSession", "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", "maxLength": 128, "description": "Session identifier lifted from instrumentation. Up to 128 characters." }, "required": true, "description": "Session identifier lifted from instrumentation. Up to 128 characters.", "name": "sessionId", "in": "path" } ], "responses": { "200": { "description": "Session detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionDetail" } } } }, "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}/sessions/{sessionId}/traces": { "get": { "tags": [ "Sessions" ], "x-fern-sdk-group-name": "sessions", "x-fern-sdk-method-name": "listTraces", "summary": "List session traces", "description": "Returns a cursor-paginated page of the traces that belong to the session. Rows match the trace list shape and exclude per-message LLM content — use `getTrace` for the full conversation view.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "listSessionTraces", "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", "maxLength": 128, "description": "Session identifier lifted from instrumentation. Up to 128 characters." }, "required": true, "description": "Session identifier lifted from instrumentation. Up to 128 characters.", "name": "sessionId", "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": [ "startTime", "endTime", "durationNs", "tokensTotal", "costTotalMicrocents" ], "default": "startTime", "description": "Field to sort by. Defaults to `startTime`." }, "required": false, "description": "Field to sort by. Defaults to `startTime`.", "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}/sessions/{sessionId}/signals": { "get": { "tags": [ "Sessions" ], "x-fern-sdk-group-name": "sessions", "x-fern-sdk-method-name": "listSignals", "summary": "List session signals", "description": "Returns the signals that occurred in the session, with occurrence stats scoped to the session's traces. Ordered by most recent occurrence first.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "listSessionSignals", "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", "maxLength": 128, "description": "Session identifier lifted from instrumentation. Up to 128 characters." }, "required": true, "description": "Session identifier lifted from instrumentation. Up to 128 characters.", "name": "sessionId", "in": "path" } ], "responses": { "200": { "description": "Signals of the session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionSignals" } } } }, "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}/sessions/{sessionId}/signals/{signalSlug}": { "get": { "tags": [ "Sessions" ], "x-fern-sdk-group-name": "sessions", "x-fern-sdk-method-name": "getSignal", "summary": "Get session signal", "description": "Returns one signal by slug, with occurrence stats scoped to the session. Returns 404 when the signal has no occurrences in the session.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "getSessionSignal", "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", "maxLength": 128, "description": "Session identifier lifted from instrumentation. Up to 128 characters." }, "required": true, "description": "Session identifier lifted from instrumentation. Up to 128 characters.", "name": "sessionId", "in": "path" }, { "schema": { "type": "string", "description": "Signal slug." }, "required": true, "description": "Signal slug.", "name": "signalSlug", "in": "path" } ], "responses": { "200": { "description": "Session signal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionSignal" } } } }, "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}/sessions/{sessionId}/memory": { "get": { "tags": [ "Sessions" ], "x-fern-sdk-group-name": "sessions", "x-fern-sdk-method-name": "getMemory", "summary": "Get session memory footprint", "description": "Returns the session's memory footprint: per-record read, added, and removed token metrics plus session-wide totals. Pass `traceId` to restrict the footprint to a single trace of the session.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "getSessionMemory", "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", "maxLength": 128, "description": "Session identifier lifted from instrumentation. Up to 128 characters." }, "required": true, "description": "Session identifier lifted from instrumentation. Up to 128 characters.", "name": "sessionId", "in": "path" }, { "schema": { "type": "string", "minLength": 32, "maxLength": 32, "description": "Restrict the memory footprint to this trace of the session. Omit for the whole session." }, "required": false, "description": "Restrict the memory footprint to this trace of the session. Omit for the whole session.", "name": "traceId", "in": "query" } ], "responses": { "200": { "description": "Session memory footprint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionMemorySummary" } } } }, "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}/sessions/{sessionId}/memory/changes": { "get": { "tags": [ "Sessions" ], "x-fern-sdk-group-name": "sessions", "x-fern-sdk-method-name": "getMemoryChanges", "summary": "Get session memory changes", "description": "Returns the memory writes the session made as per-record before/after diffs. Pass `traceId` to restrict to a single trace of the session.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "getSessionMemoryChanges", "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", "maxLength": 128, "description": "Session identifier lifted from instrumentation. Up to 128 characters." }, "required": true, "description": "Session identifier lifted from instrumentation. Up to 128 characters.", "name": "sessionId", "in": "path" }, { "schema": { "type": "string", "minLength": 32, "maxLength": 32, "description": "Restrict the memory changes to this trace of the session. Omit for the whole session." }, "required": false, "description": "Restrict the memory changes to this trace of the session. Omit for the whole session.", "name": "traceId", "in": "query" } ], "responses": { "200": { "description": "Session memory changes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionMemoryChanges" } } } }, "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}/memory/stores": { "get": { "tags": [ "Memory" ], "x-fern-sdk-group-name": "memory", "x-fern-sdk-method-name": "listStores", "summary": "List memory stores", "description": "Returns a cursor-paginated page of the project's memory stores, one roll-up row each (record count, tokens, last-updated, sessions, users). A store groups records under `gen_ai.memory.store.id`; the empty-string store is the unattributed bucket.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "listMemoryStores", "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": [ "lastUpdated", "lastRead", "records", "tokens", "sessions", "users" ], "default": "lastUpdated", "description": "Field to sort by. Defaults to `lastUpdated` (most recently written first)." }, "required": false, "description": "Field to sort by. Defaults to `lastUpdated` (most recently written first).", "name": "sort", "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": "direction", "in": "query" } ], "responses": { "200": { "description": "Page of memory stores", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedMemoryStores" } } } }, "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}/memory/store": { "get": { "tags": [ "Memory" ], "x-fern-sdk-group-name": "memory", "x-fern-sdk-method-name": "getStore", "summary": "Get memory store snapshot", "description": "Returns the store's current records (ids, token counts, last-updated) as a snapshot. Pass `at` (ISO-8601) to reconstruct the store as of a past point in time. Record bodies are fetched separately, one record at a time.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "getMemoryStore", "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": "Store identifier (`gen_ai.memory.store.id`). Pass an empty string to address the unattributed (\"\") store." }, "required": true, "description": "Store identifier (`gen_ai.memory.store.id`). Pass an empty string to address the unattributed (\"\") store.", "name": "storeId", "in": "query" }, { "schema": { "type": "string", "format": "date-time", "description": "Reconstruct the store as of this ISO-8601 timestamp. Defaults to the current state." }, "required": false, "description": "Reconstruct the store as of this ISO-8601 timestamp. Defaults to the current state.", "name": "at", "in": "query" } ], "responses": { "200": { "description": "Memory store snapshot", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryStoreSnapshot" } } } }, "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}/memory/store/diff": { "get": { "tags": [ "Memory" ], "x-fern-sdk-group-name": "memory", "x-fern-sdk-method-name": "getStoreDiff", "summary": "Diff a memory store between two points in time", "description": "Returns a per-record diff of the store between two points in time — added, updated, and removed records with token deltas. `from` defaults to the empty state (everything counts as added); `to` defaults to the current state. Unchanged records are pruned.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "getMemoryStoreDiff", "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": "Store identifier (`gen_ai.memory.store.id`). Pass an empty string to address the unattributed (\"\") store." }, "required": true, "description": "Store identifier (`gen_ai.memory.store.id`). Pass an empty string to address the unattributed (\"\") store.", "name": "storeId", "in": "query" }, { "schema": { "type": "string", "format": "date-time", "description": "Lower bound (inclusive) of the diff, ISO-8601. Defaults to the empty state." }, "required": false, "description": "Lower bound (inclusive) of the diff, ISO-8601. Defaults to the empty state.", "name": "from", "in": "query" }, { "schema": { "type": "string", "format": "date-time", "description": "Upper bound (inclusive) of the diff, ISO-8601. Defaults to the current state." }, "required": false, "description": "Upper bound (inclusive) of the diff, ISO-8601. Defaults to the current state.", "name": "to", "in": "query" } ], "responses": { "200": { "description": "Memory store diff", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryStoreDiff" } } } }, "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}/memory/store/users": { "get": { "tags": [ "Memory" ], "x-fern-sdk-group-name": "memory", "x-fern-sdk-method-name": "listStoreUsers", "summary": "List users who accessed a memory store", "description": "Returns the end-users who accessed the store (reads and writes both count as access), most recent access first. Capped at the 1000 most recent accessors.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "listMemoryStoreUsers", "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": "Store identifier (`gen_ai.memory.store.id`). Pass an empty string to address the unattributed (\"\") store." }, "required": true, "description": "Store identifier (`gen_ai.memory.store.id`). Pass an empty string to address the unattributed (\"\") store.", "name": "storeId", "in": "query" } ], "responses": { "200": { "description": "Users of the store", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryStoreUsers" } } } }, "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}/memory/record": { "get": { "tags": [ "Memory" ], "x-fern-sdk-group-name": "memory", "x-fern-sdk-method-name": "getRecord", "summary": "Get a memory record", "description": "Returns one record's current body plus its mutating version history (newest first), each version carrying the authoring span/trace/session/user and per-version token deltas.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "getMemoryRecord", "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": "Store identifier (`gen_ai.memory.store.id`). Pass an empty string to address the unattributed (\"\") store." }, "required": true, "description": "Store identifier (`gen_ai.memory.store.id`). Pass an empty string to address the unattributed (\"\") store.", "name": "storeId", "in": "query" }, { "schema": { "type": "string", "description": "Record identifier (`gen_ai.memory.record.id`). Pass an empty string to address the unnamed record." }, "required": true, "description": "Record identifier (`gen_ai.memory.record.id`). Pass an empty string to address the unnamed record.", "name": "recordId", "in": "query" } ], "responses": { "200": { "description": "Memory record detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryRecordDetail" } } } }, "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}/memory/record/change": { "get": { "tags": [ "Memory" ], "x-fern-sdk-group-name": "memory", "x-fern-sdk-method-name": "getRecordChange", "summary": "Diff a single memory record change", "description": "Returns the before/after bodies for one change — the version authored by `spanId` against its predecessor in the record's mutating chain. Returns 404 when the span is not a recorded change of the record.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "getMemoryRecordChange", "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": "Store identifier (`gen_ai.memory.store.id`). Pass an empty string to address the unattributed (\"\") store." }, "required": true, "description": "Store identifier (`gen_ai.memory.store.id`). Pass an empty string to address the unattributed (\"\") store.", "name": "storeId", "in": "query" }, { "schema": { "type": "string", "description": "Record identifier (`gen_ai.memory.record.id`). Pass an empty string to address the unnamed record." }, "required": true, "description": "Record identifier (`gen_ai.memory.record.id`). Pass an empty string to address the unnamed record.", "name": "recordId", "in": "query" }, { "schema": { "type": "string", "minLength": 16, "maxLength": 16, "description": "Span that authored the change (the `after` side)." }, "required": true, "description": "Span that authored the change (the `after` side).", "name": "spanId", "in": "query" } ], "responses": { "200": { "description": "Memory record change diff", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryRecordChangeDiff" } } } }, "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}/memory/record/reads": { "get": { "tags": [ "Memory" ], "x-fern-sdk-group-name": "memory", "x-fern-sdk-method-name": "listRecordReads", "summary": "List reads of a memory record", "description": "Returns the retrieval (`search_memory`) events for one record, newest first and capped, each with the query text (when captured), tokens returned, and the accessing span/trace/session/user.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "listMemoryRecordReads", "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": "Store identifier (`gen_ai.memory.store.id`). Pass an empty string to address the unattributed (\"\") store." }, "required": true, "description": "Store identifier (`gen_ai.memory.store.id`). Pass an empty string to address the unattributed (\"\") store.", "name": "storeId", "in": "query" }, { "schema": { "type": "string", "description": "Record identifier (`gen_ai.memory.record.id`). Pass an empty string to address the unnamed record." }, "required": true, "description": "Record identifier (`gen_ai.memory.record.id`). Pass an empty string to address the unnamed record.", "name": "recordId", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 200, "description": "Maximum number of read events to return. Capped at 200." }, "required": false, "description": "Maximum number of read events to return. Capped at 200.", "name": "limit", "in": "query" } ], "responses": { "200": { "description": "Reads of the record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryRecordReads" } } } }, "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}/memory/record/users": { "get": { "tags": [ "Memory" ], "x-fern-sdk-group-name": "memory", "x-fern-sdk-method-name": "listRecordUsers", "summary": "List users who accessed a memory record", "description": "Returns the end-users who accessed one record with per-user read and write counts, most recent access first. Capped at the 1000 most recent accessors.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "listMemoryRecordUsers", "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": "Store identifier (`gen_ai.memory.store.id`). Pass an empty string to address the unattributed (\"\") store." }, "required": true, "description": "Store identifier (`gen_ai.memory.store.id`). Pass an empty string to address the unattributed (\"\") store.", "name": "storeId", "in": "query" }, { "schema": { "type": "string", "description": "Record identifier (`gen_ai.memory.record.id`). Pass an empty string to address the unnamed record." }, "required": true, "description": "Record identifier (`gen_ai.memory.record.id`). Pass an empty string to address the unnamed record.", "name": "recordId", "in": "query" } ], "responses": { "200": { "description": "Users of the record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryRecordUsers" } } } }, "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": {} }