Read aggregated API and webhook usage, request logs, and endpoint metering metadata.

Usage & Metering API

Read aggregated API and webhook usage, browse request log entries, and discover endpoint metering metadata. These meta endpoints support the API Console and external monitoring integrations.

All endpoints in this document require Sanctum bearer authentication and are declared with price weight 0 — they are logged but do not consume weighted metering units.

Unit weighting matrix#

Every /api/v1 request consumes a fixed number of units based on the endpoint's declared #[PriceWeight]. Weights reflect the worst-case query plan, not the average request. There are no weights at 5 or 7.

Tie-breaker#

If an endpoint can be cheap or expensive depending on query parameters, it is priced at its worst-case plan. For example, a list that accepts deep Ransack filters and relation includes is weight 2, even when most callers page a small unfiltered set.

What is metered#

Metering covers token-authenticated traffic only: requests to /api/v1 and calls made through the MCP server, including plugin-bridged MCP tools — every programmatic surface drains the same per-token unit throughput bucket. Web-UI sessions are deliberately not metered: a human working the interface is paced by the interface itself, whereas programmatic callers can issue expensive work in unbounded loops, and it is that traffic the budget exists to shape. Commercial metering and plan quotas layer on top of this same enforcement point rather than introducing a second one, so the scope above holds for them too.

Prefer webhooks over polling#

Polling expensive endpoints burns units quickly. Prefer outbound webhooks for change notification.

Example: Polling an availability endpoint at weight 6 every 30 seconds is roughly 17,280 units/day (6 × 2 × 60 × 24) — over 500,000 units/month, before any other traffic. Subscribe to webhook events instead.

Endpoints#

Authentication#

Requires a Sanctum bearer token with the ability shown above. Requests without the required ability receive 403.

List Usage#

GET /api/v1/usage

Returns grouped aggregates from the usage_daily rollup table.

Query parameters#

Response#

{
    "usage": [
        {
            "key": "api.v1.accounts.index",
            "label": null,
            "request_count": 142,
            "weighted_units": 284
        }
    ],
    "meta": {
        "totals": {
            "request_count": 1250,
            "weighted_units": 980
        },
        "window": {
            "preset": "7d",
            "from": "2026-06-25T00:00:00+00:00",
            "to": "2026-07-01T14:30:00+00:00"
        },
        "dimension": "endpoint"
    }
}

Export Usage#

GET /api/v1/usage/export

Accepts the same query parameters as GET /api/v1/usage. Dispatches an ExportApiUsage job and returns 202 Accepted with a job identifier. The CSV is delivered asynchronously (same export pipeline as the Usage dashboard).

List Request Logs#

GET /api/v1/request_logs

Returns paginated detail rows from request_logs (API requests, outbound webhook deliveries, and inbound webhook receipts).

Filters (Ransack)#

Sorts#

Pagination#

Standard offset pagination: ?page=2&per_page=20.

Response#

{
    "request_logs": [
        {
            "id": 1,
            "channel": "api",
            "request_id": "550e8400-e29b-41d4-a716-446655440000",
            "method": "GET",
            "uri": "/api/v1/accounts",
            "route_name": "api.v1.accounts.index",
            "resource": "accounts",
            "operation": "index",
            "personal_access_token_id": 3,
            "user_id": 1,
            "ability": "accounts:read",
            "status_code": 200,
            "duration_ms": 45,
            "request_bytes": 0,
            "response_bytes": 2048,
            "price_weight": 2,
            "weighted_units": 2,
            "ip_address": "127.0.0.1",
            "user_agent": "Signals-Explorer/1.0",
            "created_at": "2026-07-01T14:30:00Z"
        }
    ],
    "meta": {
        "total": 500,
        "per_page": 20,
        "page": 1
    }
}

Detail log CSV export is available from the API Console Request Log UI (not exposed as a REST endpoint).

List Endpoints#

GET /api/v1/endpoints

Returns every registered v1 route with metering metadata from ApiEndpointCatalogue and PriceWeightResolver.

Response#

{
    "endpoints": [
        {
            "name": "api.v1.accounts.index",
            "method": "GET",
            "uri": "/api/v1/accounts",
            "resource": "accounts",
            "operation": "index",
            "ability": "accounts:read",
            "price_weight": 2
        },
        {
            "name": "api.v1.usage.index",
            "method": "GET",
            "uri": "/api/v1/usage",
            "resource": null,
            "operation": null,
            "ability": "api-usage:read",
            "price_weight": 0
        }
    ]
}

Use this catalogue to discover required abilities and price weights before integrating. Weights of 0 indicate endpoints that are logged but excluded from weighted metering totals. The OpenAPI reference at /docs/api also surfaces each operation's unit cost as Cost: N units and the x-signals-units extension property.

Metering channels#

Related documentation#

• API Console (platform) — Explorer, Request Log, Usage dashboard, and Webhooks UI
• Webhooks — outbound subscriptions and inbound receiver