{"openapi":"3.1.0","info":{"title":"Respan Metrics (BYOK) API","version":"0.1.0","description":"Respan Metrics (BYOK) lets an AI assistant read your own Respan Metrics data through the Respan Metrics API with a key you supply (Respan API key (read permission is enough)). Read-only: 7 tools (get_llm_metric_summary, get_llm_metrics_over_time, get_quantile_summary, get_cache_hit_summary, get_cache_hits_over_time, get_active_users_over_time, get_storage_volume_summary). The BYOK key travels...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-respan-metrics.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-respan-metrics/docs"},"termsOfService":"https://connectorbay.com/byok-respan-metrics/terms"},"servers":[{"url":"https://byok-respan-metrics.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-respan-metrics/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/get_llm_metric_summary":{"post":{"operationId":"get_llm_metric_summary","summary":"Get one aggregated row for a time range: request count, cost in USD, prompt and completion tokens, error count and rate,","description":"Get one aggregated row for a time range: request count, cost in USD, prompt and completion tokens, error count and rate, average latency, tokens per second, time to first token and cache hit rate. Use for \"How many requests and how much did my LLM usage cost in Respan over the last 24 hours\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"summary_type":{"anyOf":[{"enum":["daily","weekly","monthly","quarterly","yearly","last_24h","all"],"type":"string"},{"type":"null"}],"default":"last_24h","description":"Preset time range: daily, weekly, monthly, quarterly, yearly, last_24h or all. Ignored when start_time and end_time are given.","title":"Summary Type"},"start_time":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Optional explicit range start as an ISO 8601 time, for example 2026-10-01T00:00:00Z (use together with end_time).","title":"Start Time"},"end_time":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Optional explicit range end as an ISO 8601 time, for example 2026-10-08T00:00:00Z.","title":"End Time"}},"title":"get_llm_metric_summaryArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_llm_metrics_over_time":{"post":{"operationId":"get_llm_metrics_over_time","summary":"Get the same usage, cost, latency and error metrics as a time series, one row per minute, hour or day, plus the total fo","description":"Get the same usage, cost, latency and error metrics as a time series, one row per minute, hour or day, plus the total for the range. Use for \"Show my daily LLM cost and error rate in Respan for the last month\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"summary_type":{"anyOf":[{"enum":["daily","weekly","monthly","quarterly","yearly","last_24h","all"],"type":"string"},{"type":"null"}],"default":"last_24h","description":"Preset time range: daily, weekly, monthly, quarterly, yearly, last_24h or all. Ignored when start_time and end_time are given.","title":"Summary Type"},"start_time":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Optional explicit range start as an ISO 8601 time, for example 2026-10-01T00:00:00Z (use together with end_time).","title":"Start Time"},"end_time":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Optional explicit range end as an ISO 8601 time, for example 2026-10-08T00:00:00Z.","title":"End Time"},"time_tick":{"anyOf":[{"enum":["minute","hour","day"],"type":"string"},{"type":"null"}],"default":"day","description":"Bucket size of the time series: minute, hour or day.","title":"Time Tick"}},"title":"get_llm_metrics_over_timeArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_quantile_summary":{"post":{"operationId":"get_quantile_summary","summary":"Get latency, time-to-first-token, tokens-per-second and token-count percentiles (p50, p90, p95, p99) for a time range. U","description":"Get latency, time-to-first-token, tokens-per-second and token-count percentiles (p50, p90, p95, p99) for a time range. Use for \"What are my p95 and p99 LLM latencies in Respan this week\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"summary_type":{"anyOf":[{"enum":["daily","weekly","monthly","quarterly","yearly","last_24h","all"],"type":"string"},{"type":"null"}],"default":"last_24h","description":"Preset time range: daily, weekly, monthly, quarterly, yearly, last_24h or all. Ignored when start_time and end_time are given.","title":"Summary Type"},"start_time":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Optional explicit range start as an ISO 8601 time, for example 2026-10-01T00:00:00Z (use together with end_time).","title":"Start Time"},"end_time":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Optional explicit range end as an ISO 8601 time, for example 2026-10-08T00:00:00Z.","title":"End Time"}},"title":"get_quantile_summaryArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_cache_hit_summary":{"post":{"operationId":"get_cache_hit_summary","summary":"Get cache hit totals for a time range: requests served from cache, tokens, time saved and cost. Use for \"How much did th","description":"Get cache hit totals for a time range: requests served from cache, tokens, time saved and cost. Use for \"How much did the Respan cache save me this week\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"summary_type":{"anyOf":[{"enum":["daily","weekly","monthly","quarterly","yearly","last_24h","all"],"type":"string"},{"type":"null"}],"default":"last_24h","description":"Preset time range: daily, weekly, monthly, quarterly, yearly, last_24h or all. Ignored when start_time and end_time are given.","title":"Summary Type"},"start_time":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Optional explicit range start as an ISO 8601 time, for example 2026-10-01T00:00:00Z (use together with end_time).","title":"Start Time"},"end_time":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Optional explicit range end as an ISO 8601 time, for example 2026-10-08T00:00:00Z.","title":"End Time"}},"title":"get_cache_hit_summaryArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_cache_hits_over_time":{"post":{"operationId":"get_cache_hits_over_time","summary":"Get cache hit metrics as a time series (requests, tokens, time saved, cost per bucket). Use for \"Show cache hits per day","description":"Get cache hit metrics as a time series (requests, tokens, time saved, cost per bucket). Use for \"Show cache hits per day in Respan this month\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"summary_type":{"anyOf":[{"enum":["daily","weekly","monthly","quarterly","yearly","last_24h","all"],"type":"string"},{"type":"null"}],"default":"last_24h","description":"Preset time range: daily, weekly, monthly, quarterly, yearly, last_24h or all. Ignored when start_time and end_time are given.","title":"Summary Type"},"start_time":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Optional explicit range start as an ISO 8601 time, for example 2026-10-01T00:00:00Z (use together with end_time).","title":"Start Time"},"end_time":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Optional explicit range end as an ISO 8601 time, for example 2026-10-08T00:00:00Z.","title":"End Time"},"time_tick":{"anyOf":[{"enum":["minute","hour","day"],"type":"string"},{"type":"null"}],"default":"day","description":"Bucket size of the time series: minute, hour or day.","title":"Time Tick"}},"title":"get_cache_hits_over_timeArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_active_users_over_time":{"post":{"operationId":"get_active_users_over_time","summary":"Get how many distinct end users were active per time bucket, with total and average cost per user (counts only, no user ","description":"Get how many distinct end users were active per time bucket, with total and average cost per user (counts only, no user identifiers). Use for \"How many active users did my app have per day in Respan\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"summary_type":{"anyOf":[{"enum":["daily","weekly","monthly","quarterly","yearly","last_24h","all"],"type":"string"},{"type":"null"}],"default":"last_24h","description":"Preset time range: daily, weekly, monthly, quarterly, yearly, last_24h or all. Ignored when start_time and end_time are given.","title":"Summary Type"},"start_time":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Optional explicit range start as an ISO 8601 time, for example 2026-10-01T00:00:00Z (use together with end_time).","title":"Start Time"},"end_time":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Optional explicit range end as an ISO 8601 time, for example 2026-10-08T00:00:00Z.","title":"End Time"},"time_tick":{"anyOf":[{"enum":["minute","hour","day"],"type":"string"},{"type":"null"}],"default":"day","description":"Bucket size of the time series: minute, hour or day.","title":"Time Tick"}},"title":"get_active_users_over_timeArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_storage_volume_summary":{"post":{"operationId":"get_storage_volume_summary","summary":"Get how much log data the workspace stores: total bytes, object count and bytes per storage class. Use for \"How much log","description":"Get how much log data the workspace stores: total bytes, object count and bytes per storage class. Use for \"How much log storage is my Respan workspace using\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"summary_type":{"anyOf":[{"enum":["daily","weekly","monthly","quarterly","yearly","last_24h","all"],"type":"string"},{"type":"null"}],"default":"all","description":"Preset time range: daily, weekly, monthly, quarterly, yearly, last_24h or all.","title":"Summary Type"}},"title":"get_storage_volume_summaryArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}