API reference

The Apidepth collector exposes a REST API at https://collector.apidepth.io. All endpoints require a Bearer token (your API key) in the Authorization header.

Authorization: Bearer apd_your_api_key

POST/v1/events

Ingest a batch of API call events. Used by the SDK — you typically do not call this directly.

Body parameters

batchArray<Event>requiredArray of event objects (max 100 per request).

sdkObjectSDK metadata (name, version, runtime). Added automatically by the SDK.

extra_vendorsObjectCustomer-defined vendor mappings forwarded from config.extra_vendors.

Response fields

receivedIntegerNumber of events accepted.

Example response

{ "received": 12 }

GET/v1/vendors

List vendors seen in the last 30 days for the authenticated customer.

Query parameters

envStringFilter by environment (e.g. production). Returns all environments if omitted.

Response fields

vendorsArray<String>Sorted list of vendor slugs.

Example response

{ "vendors": ["anthropic", "openai", "stripe"] }

GET/v1/endpoints

List normalised endpoints seen for a vendor.

Query parameters

vendorStringrequiredVendor slug (e.g. stripe).

envStringFilter by environment.

Response fields

endpointsArray<String>Sorted list of normalised path strings.

Example response

{ "endpoints": ["/v1/charges/:id", "/v1/customers/:id"] }

GET/v1/latency

Hourly latency percentiles and error counts for a vendor, optionally filtered to one endpoint.

Query parameters

vendorStringrequiredVendor slug.

endpointStringNormalised path (e.g. /v1/charges/:id). Omit to aggregate across all endpoints.

envStringEnvironment filter.

fromISO 8601Start of time range. Defaults to 24 h ago.

toISO 8601End of time range. Defaults to now.

Response fields

bucketsArray<Bucket>Hourly buckets ordered by time ascending.

buckets[].bucketString (ISO 8601)Start of the hour.

buckets[].p50Float50th percentile latency in milliseconds.

buckets[].p95Float95th percentile latency in milliseconds.

buckets[].p99Float99th percentile latency in milliseconds.

buckets[].event_countIntegerRequests with valid latency data in this bucket.

buckets[].error_countIntegerRequests with 4xx/5xx or timeout status.

buckets[].total_countIntegerTotal requests in the bucket (event_count + requests with no latency data).

Example response

{
  "buckets": [
    { "bucket": "2026-05-18T00:00:00Z", "p50": 182.4, "p95": 421.1, "p99": 680.0,
      "event_count": 340, "error_count": 4, "total_count": 344 }
  ]
}

GET/v1/fleet-benchmarks

Anonymised fleet-wide latency percentiles bucketed hourly. Only buckets with at least 10 contributing customers are included.

Query parameters

vendorStringrequiredVendor slug.

endpointStringNormalised path. Omit to aggregate across all endpoints.

fromISO 8601Start of time range.

toISO 8601End of time range.

Response fields

bucketsArray<Bucket>Hourly fleet buckets ordered by time ascending.

buckets[].bucketString (ISO 8601)Start of the hour.

buckets[].fleet_p50FloatFleet median latency in milliseconds.

buckets[].fleet_p95FloatFleet 95th percentile in milliseconds.

buckets[].contributor_countIntegerDistinct customers contributing data to this bucket.

Example response

{
  "buckets": [
    { "bucket": "2026-05-18T00:00:00Z", "fleet_p50": 210.0, "fleet_p95": 566.0, "contributor_count": 1240 }
  ]
}

GET/v1/rate-limits

429 frequency summary across vendors, or hourly detail for a specific vendor including burn-down data.

Query parameters

vendorStringIf omitted, returns a summary across all vendors. If provided, returns hourly detail for that vendor.

envStringEnvironment filter.

fromISO 8601Start of time range.

toISO 8601End of time range.

Response fields

vendorsArray<VendorSummary>(Summary mode) Per-vendor 429 counts and top throttled endpoint.

total_429sInteger(Detail mode) Total 429 responses in the time range.

trend_pctFloat | null(Detail mode) Percentage change vs. the previous equivalent period.

top_endpointString | null(Detail mode) Most-throttled normalised path.

bucketsArray<Bucket>(Detail mode) Hourly 429 counts.

burn_downBurnDown | null(Detail mode) Live quota snapshot and projection. null if no header data captured yet.

burn_down.rl_remainingIntegerRequests remaining in the current window.

burn_down.rl_limitInteger | nullTotal window quota.

burn_down.rl_reset_atString (ISO 8601) | nullWhen the quota window resets.

burn_down.burn_rate_per_minFloatRequests per minute over the last 5 minutes.

burn_down.minutes_to_throttleFloat | nullProjected minutes until quota exhaustion at current burn rate.

burn_down.risk"high" | "medium" | "low" | nullRisk level based on minutes_to_throttle.

Example response

{
  "total_429s": 42,
  "trend_pct": 15.3,
  "top_endpoint": "/v1/chat/completions",
  "buckets": [
    { "bucket": "2026-05-18T00:00:00Z", "count": 7 }
  ],
  "burn_down": {
    "rl_remaining": 340,
    "rl_limit": 10000,
    "rl_reset_at": "2026-05-18T03:15:00Z",
    "burn_rate_per_min": 42.0,
    "minutes_to_throttle": 8.1,
    "risk": "high"
  }
}

GET/v1/model-usage

List all AI models the authenticated customer's code has called, enriched with deprecation status from the Apidepth catalog. Powers the Model Radar page. Available on all tiers.

Response fields

modelsArray<ModelEntry>One entry per unique (vendor, model_name, endpoint) combination.

models[].vendorStringVendor slug (e.g. openai, anthropic).

models[].model_nameStringModel identifier as returned by the vendor API (e.g. gpt-4-turbo).

models[].endpointStringNormalised API endpoint path.

models[].call_countIntegerCumulative calls recorded by the SDK.

models[].first_seen_atString (ISO 8601)When this model was first observed.

models[].last_seen_atString (ISO 8601)Most recent call timestamp.

models[].vendorStringVendor slug (e.g. openai, anthropic).

models[].model_nameStringModel identifier as returned by the vendor API (e.g. gpt-4-turbo).

models[].endpointStringNormalised API endpoint path.

models[].call_countIntegerCumulative calls recorded by the SDK.

models[].first_seen_atString (ISO 8601)When this model was first observed.

models[].last_seen_atString (ISO 8601)Most recent call timestamp.

models[].deprecation_status"active" | "deprecated" | "sunset"active — not in the deprecation catalog or not yet deprecated. deprecated — deprecated_at has passed but sunset_at is in the future. sunset — sunset_at has passed; continued calls may return errors.

models[].deprecated_atString (YYYY-MM-DD) | nullDate the model was deprecated. null if not deprecated.

models[].sunset_atString (YYYY-MM-DD) | nullDate the model was or will be shut down. null if not scheduled.

models[].successorString | nullRecommended replacement model. null if no successor is catalogued.

models[].deprecated_atString (YYYY-MM-DD) | nullDate the model was deprecated. null if not deprecated.

models[].sunset_atString (YYYY-MM-DD) | nullDate the model was or will be shut down. null if not scheduled.

models[].successorString | nullRecommended replacement model. null if no successor is catalogued.

Example response

{
  "models": [
    {
      "vendor": "openai",
      "model_name": "gpt-4-turbo",
      "endpoint": "/v1/chat/completions",
      "call_count": 14203,
      "first_seen_at": "2026-04-01T00:00:00Z",
      "last_seen_at": "2026-05-27T11:30:00Z",
      "deprecation_status": "active",
      "deprecated_at": null,
      "sunset_at": null,
      "successor": null
    },
    {
      "vendor": "openai",
      "model_name": "gpt-3.5-turbo-0301",
      "endpoint": "/v1/chat/completions",
      "call_count": 872,
      "first_seen_at": "2026-03-15T00:00:00Z",
      "last_seen_at": "2026-05-26T22:14:00Z",
      "deprecation_status": "deprecated",
      "deprecated_at": "2024-06-13",
      "sunset_at": "2025-01-01",
      "successor": "gpt-3.5-turbo"
    }
  ]
}

GET/v1/health-scores

Latest dependency health snapshot per vendor for the authenticated customer, plus a volume-weighted aggregate. Each score is a composite 0–100 signal derived from four sub-scores: latency p95 vs 7-day baseline, 24-hour error rate, rate-limit remaining ratio, and vendor status page indicator. Sub-scores with no data are excluded and remaining weights re-proportioned. Available on all tiers.

Response fields

scoresArray<HealthScore>One entry per tracked vendor.

scores[].vendorStringVendor slug.

scores[].scoreInteger (0–100) | nullComposite health score. null when no data is available for this vendor yet.

scores[].latency_subInteger (0–100) | nullLatency sub-score: p95 vs 7-day baseline.

scores[].error_subInteger (0–100) | nullError-rate sub-score: 24-hour error rate.

scores[].rate_subInteger (0–100) | nullRate-limit sub-score: rl_remaining / rl_limit ratio.

scores[].status_subInteger (0–100) | nullVendor status page sub-score from the probe worker.

scores[].call_volumeIntegerRequests to this vendor in the last 24 hours (used for volume weighting).

scores[].computed_atString (ISO 8601)When this snapshot was last computed.

aggregateInteger (0–100) | nullVolume-weighted mean across all vendors. null when all vendors lack scores.

Example response

{
  "scores": [
    {
      "vendor": "openai",
      "score": 82,
      "latency_sub": 78,
      "error_sub": 95,
      "rate_sub": 90,
      "status_sub": 100,
      "call_volume": 14200,
      "computed_at": "2026-06-03T08:00:00Z"
    }
  ],
  "aggregate": 84
}

GET/v1/status

Apidepth's own uptime status. Public — no authentication required. Returns current operational status, 30-day and 90-day uptime percentages, a 90-day daily breakdown, and the 10 most recent incidents.

Response fields

status"operational" | "outage" | "unknown"Current status derived from the most recent health check.

checked_atString (ISO 8601) | nullTimestamp of the most recent health check.

response_msInteger | nullDatabase response time of the most recent check.

uptime_30dFloat | nullUptime percentage over the last 30 days.

uptime_90dFloat | nullUptime percentage over the last 90 days.

daysArray<DayUptime>Per-day uptime breakdown for the last 90 days, sorted ascending.

days[].dateString (YYYY-MM-DD)Calendar date.

days[].totalIntegerTotal health checks recorded for this day.

days[].up_countIntegerNumber of successful checks.

days[].uptime_pctFloat | nullUptime percentage for this day.

incidentsArray<Incident>Up to 10 most recent incidents (consecutive failed checks), newest first.

incidents[].started_atString (ISO 8601)When the incident began.

incidents[].ended_atString (ISO 8601)When the incident ended (last failed check in the run).

incidents[].duration_minIntegerIncident duration in minutes.

Example response

{
  "status": "operational",
  "checked_at": "2026-06-03T08:02:00Z",
  "response_ms": 3,
  "uptime_30d": 99.98,
  "uptime_90d": 99.96,
  "days": [
    { "date": "2026-06-02", "total": 1440, "up_count": 1440, "uptime_pct": 100.0 }
  ],
  "incidents": []
}

GET/v1/environments

Return the distinct environment tags seen in the last 30 days for the authenticated customer. Used to populate the environment switcher in the dashboard sidebar.

Response fields

environmentsArray<String>Sorted list of environment strings (e.g. production, staging).

Example response

{ "environments": ["production", "staging"] }

GET/v1/maintenance-windows

List all maintenance windows for the authenticated customer, ordered by start time.

Response fields

windowsArray<Window>All windows for this account.

windows[].idUUIDWindow identifier.

windows[].vendorStringVendor slug this window suppresses.

windows[].labelStringHuman-readable label.

windows[].starts_atString (ISO 8601)Window start time.

windows[].ends_atString (ISO 8601)Window end time.

windows[].is_activeBooleanTrue when the current time is between starts_at and ends_at.

windows[].created_atString (ISO 8601)Creation timestamp.

Example response

{
  "windows": [
    {
      "id": "a1b2c3d4-...",
      "vendor": "stripe",
      "label": "Stripe migration",
      "starts_at": "2026-06-01T02:00:00+00:00",
      "ends_at": "2026-06-01T04:00:00+00:00",
      "is_active": false,
      "created_at": "2026-05-28T10:00:00+00:00"
    }
  ]
}

POST/v1/maintenance-windows

Create a maintenance window. All alerts for the specified vendor are suppressed while the window is active. Requires Solo or Team plan.

Body parameters

vendorStringrequiredVendor slug to suppress. Must already be tracked by your account.

labelStringrequiredShort description, e.g. "Stripe migration". Max 100 characters.

starts_atISO 8601requiredWindow start time. Must be in the future and include timezone.

ends_atISO 8601requiredWindow end time. Must be after starts_at. Maximum duration is 7 days.

Response fields

idUUIDCreated window ID.

vendorStringVendor slug.

labelStringLabel as stored (whitespace trimmed).

starts_atString (ISO 8601)Window start time.

ends_atString (ISO 8601)Window end time.

is_activeBooleanAlways false at creation (starts_at is always in the future).

created_atString (ISO 8601)Creation timestamp.

Example response

{
  "id": "a1b2c3d4-...",
  "vendor": "stripe",
  "label": "Stripe migration",
  "starts_at": "2026-06-01T02:00:00+00:00",
  "ends_at": "2026-06-01T04:00:00+00:00",
  "is_active": false,
  "created_at": "2026-05-28T10:00:00+00:00"
}

DELETE/v1/maintenance-windows/{id}

Delete a maintenance window by ID. Returns 204 on success. Returns 404 if the window does not exist or belongs to a different account.

Response fields

(empty body)204 No Content on success.

GET/v1/slo

List all SLO definitions for the authenticated customer, ordered by creation time. Requires Solo or Team plan.

Response fields

slosArray<SloDefinition>All SLO definitions for this account.

slos[].idUUIDSLO definition identifier.

slos[].vendorStringVendor slug this SLO measures.

slos[].endpointString | nullNormalised endpoint path, or null for a vendor-wide SLO.

slos[].metric"p50" | "p95" | "p99"Latency percentile being tracked.

slos[].threshold_msIntegerBreach threshold in milliseconds.

slos[].envStringEnvironment filter (default: production).

slos[].default_window_days30 | 60 | 90Default compliance window shown in the dashboard.

slos[].created_atString (ISO 8601)Creation timestamp.

Example response

{
  "slos": [
    {
      "id": "f1e2d3c4-...",
      "vendor": "openai",
      "endpoint": "/v1/chat/completions",
      "metric": "p95",
      "threshold_ms": 2000,
      "env": "production",
      "default_window_days": 30,
      "created_at": "2026-06-03T09:00:00+00:00"
    }
  ]
}

POST/v1/slo

Create an SLO definition. The vendor must already be tracked by the account. Duplicate (vendor + endpoint + metric + env) returns 409. Requires Solo or Team plan.

Body parameters

vendorStringrequiredVendor slug to measure. Must already be tracked by your account.

endpointString | nullNormalised endpoint path. Omit or pass null for a vendor-wide SLO (uses true vendor-level percentile, not an average of per-endpoint values).

metric"p50" | "p95" | "p99"requiredLatency percentile to track against the threshold.

threshold_msIntegerrequiredBreach threshold in milliseconds. Must be greater than 0.

envStringEnvironment to measure. Defaults to production.

default_window_days30 | 60 | 90Default window shown in the dashboard. Defaults to 30. The compliance report always accepts an override via the window query param.

Response fields

idUUIDCreated SLO definition ID.

vendorStringVendor slug.

endpointString | nullEndpoint path, or null for vendor-wide.

metricStringMetric as stored.

threshold_msIntegerThreshold as stored.

envStringEnvironment as stored.

default_window_daysIntegerDefault window as stored.

created_atString (ISO 8601)Creation timestamp.

Example response

{
  "id": "f1e2d3c4-...",
  "vendor": "openai",
  "endpoint": "/v1/chat/completions",
  "metric": "p95",
  "threshold_ms": 2000,
  "env": "production",
  "default_window_days": 30,
  "created_at": "2026-06-03T09:00:00+00:00"
}

DELETE/v1/slo/{id}

Delete an SLO definition by ID. Returns 204 on success. Returns 404 if the SLO does not exist or belongs to a different account.

Response fields

(empty body)204 No Content on success.

GET/v1/sla

SLA compliance report. Returns one entry per matching SLO definition with compliance percentage, breach hours, longest consecutive breach run, and per-day heatmap data. Buckets with fewer than 20 requests are excluded from compliance counts. Requires Solo or Team plan.

Query parameters

window30 | 60 | 90Rolling window in days. When omitted, each SLO uses its own default_window_days.

vendorStringFilter results to a single vendor slug.

envStringEnvironment filter. Defaults to production.

Response fields

window_daysIntegerEffective window used (the query param, or 30 when omitted).

slosArray<SloResult>One entry per matching SLO definition.

slos[].idUUIDSLO definition identifier.

slos[].vendorStringVendor slug.

slos[].endpointString | nullEndpoint path, or null for vendor-wide.

slos[].metricStringMetric measured.

slos[].threshold_msIntegerBreach threshold.

slos[].window_daysIntegerWindow used for this SLO's compliance calculation.

slos[].compliance_pctFloat | nullPercentage of qualifying hours that met the SLO. null when there is no qualifying data in the window.

slos[].total_bucketsIntegerQualifying hourly buckets (≥20 requests) in the window.

slos[].breaching_hoursIntegerQualifying hours where the metric exceeded the threshold.

slos[].longest_breach_hoursIntegerLongest consecutive run of breaching hours. A gap (excluded or missing hour) resets the counter.

slos[].daysArray<DayEntry>Per-day breakdown for the calendar heatmap, sorted ascending.

slos[].days[].dateString (YYYY-MM-DD)Calendar date.

slos[].days[].status"met" | "missed"met if all qualifying hours passed; missed if any qualifying hour breached.

slos[].days[].total_hoursIntegerQualifying hours on this day.

slos[].days[].breaching_hoursIntegerQualifying hours that breached on this day.

Example response

{
  "window_days": 30,
  "slos": [
    {
      "id": "f1e2d3c4-...",
      "vendor": "openai",
      "endpoint": "/v1/chat/completions",
      "metric": "p95",
      "threshold_ms": 2000,
      "window_days": 30,
      "compliance_pct": 97.14,
      "total_buckets": 700,
      "breaching_hours": 20,
      "longest_breach_hours": 6,
      "days": [
        { "date": "2026-05-04", "status": "met", "total_hours": 22, "breaching_hours": 0 },
        { "date": "2026-05-05", "status": "missed", "total_hours": 24, "breaching_hours": 3 }
      ]
    }
  ]
}