Skip to content

usage-by-endpoint.md

Latest commit

 

History

History
90 lines (67 loc) · 4.18 KB

usage-by-endpoint.md

File metadata and controls

90 lines (67 loc) · 4.18 KB
Raw

GET /api/usage/by-endpoint — Top-N Endpoints per Developer

Returns the authenticated developer's most-called API endpoints ranked by call volume within a requested time window. Useful for identifying hot endpoints, spotting usage spikes, and optimising spend.

Request

GET /api/usage/by-endpoint
Authorization: Bearer <token>

Query Parameters

Parameter Type Required Default Description
from string No 30 days ago Start of period (ISO-8601, e.g. 2026-06-01T00:00:00Z)
to string No Now End of period (ISO-8601)
limit integer No 5 Maximum number of endpoints to return (≥ 1)
apiId string No all APIs Filter results to a specific registered API
  • If from and to are both omitted the last 30 days are used.
  • from must be ≤ to; otherwise a 400 is returned.
  • limit must be a positive integer; otherwise a 400 is returned.

Response

HTTP 200:

{
  "data": [
    { "endpoint": "/v1/weather/current",  "calls": 142, "revenue": "142000" },
    { "endpoint": "/v1/weather/forecast", "calls":  87, "revenue":  "87000" }
  ],
  "period": {
    "from": "2026-06-01T00:00:00.000Z",
    "to":   "2026-07-01T00:00:00.000Z"
  }
}

Response fields

Field Type Description
data array Endpoints ordered by calls descending; ties broken by path ascending.
data[].endpoint string Endpoint path identifier (e.g. /v1/weather/current).
data[].calls integer Total call count in the period.
data[].revenue string Total revenue in smallest USDC units (string to avoid precision loss).
period.from string Effective start of the query window (ISO-8601).
period.to string Effective end of the query window (ISO-8601).

Error Responses

HTTP status Code When
400 BAD_REQUEST Invalid date, from > to, or invalid limit.
401 UNAUTHORIZED Missing or invalid bearer token.
500 INTERNAL_ERROR Unexpected server error.

See docs/error-codes.md for the full error envelope format.

Authentication

Requires a valid developer bearer token (Authorization: Bearer <token>) or x-user-id header in local/test flows. Results are always scoped to the authenticated developer — cross-developer data is never returned.

Implementation notes

  • In-memory store (InMemoryUsageEventsRepository): groups events by endpoint, sums calls and revenue, then sorts by calls descending (ties broken by path ascending) before slicing to limit.
  • PostgreSQL store (PgUsageEventsRepository): issues a single GROUP BY endpoint_id ORDER BY calls DESC query with a parameterised LIMIT, running entirely within the database for efficiency.
  • The route is mounted at /api/usage/by-endpoint before the generic /api/usage mount so the more-specific path always matches first.
  • The standard REST rate limiter applies to this route (configurable via REST_RATE_LIMIT_WINDOW_MS / REST_RATE_LIMIT_MAX_REQUESTS).

Examples

Top 3 endpoints over the last 7 days

curl -s \
  -H "Authorization: Bearer $TOKEN" \
  "https://api.callora.io/api/usage/by-endpoint?limit=3&from=$(date -u -d '-7 days' +%Y-%m-%dT%H:%M:%SZ)"

Top endpoints for a specific API

curl -s \
  -H "Authorization: Bearer $TOKEN" \
  "https://api.callora.io/api/usage/by-endpoint?apiId=api_abc123&limit=10"