openapi: 3.2.0 info: title: Latitude Tools API 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 servers: - url: https://api.latitude.so tags: - name: Tools paths: /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' components: schemas: Error: type: object properties: error: type: string required: - error 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 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 nullable: true description: ISO-8601 timestamp the tool was last offered. `null` when never offered. selectionRate: type: number nullable: true 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 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 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 ToolHistogramResponse: type: object properties: items: type: array items: $ref: '#/components/schemas/ToolCallHistogramBucket' description: Call buckets across the range, oldest first. required: - items ToolUsageMetrics: type: object nullable: true 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. 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 ToolContextBreakdownResponse: type: object properties: items: type: array items: $ref: '#/components/schemas/ToolContextBreakdownRow' description: Breakdown rows, most significant first. required: - items ToolCoOccurrenceResponse: type: object properties: items: type: array items: $ref: '#/components/schemas/ToolCoOccurrenceRow' description: Co-occurring tools, by shared trace count. required: - items ToolDefinitionDetail: type: object nullable: true properties: definition: type: object nullable: true 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. 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 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 ToolErrorBreakdownResponse: type: object properties: items: type: array items: $ref: '#/components/schemas/ToolErrorBreakdownRow' description: Error clusters, most frequent first. required: - items 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 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 PaginatedToolCalls: type: object properties: items: type: array items: $ref: '#/components/schemas/RecentToolCall' description: Page of items, in the requested sort order. nextCursor: type: string nullable: true 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 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 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 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