SIGNALS Docs
Exit Reader View
100%
Theme

Reader View

Usage & Metering

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

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; the bulk availability grid has a dedicated weight of 20.

Weight Class Description Examples
0 Meta / introspection Logged but excluded from weighted totals GET /usage, GET /endpoints, GET /request_logs, GET /schema
1 Simple read Show a resource; index with standard pagination GET /accounts/{id}, GET /countries
2 Complex read / simple write Index with heavy filters/includes; search; POST/PATCH a single resource GET /catalogue_items, GET /search, POST /addresses
3 Write with side effects Fires events, webhooks, or projections Rental line changes, status transitions, flightcase pack/seal
4 Compound operation Multi-entity writes, quote/document generation, bulk reads, semantic / AI search POST /documents/generate, GET /search/semantic, rental convert / fulfilment batch dispatch
6 Availability Scans asset calendars across a date range GET /availability/calendar, /gantt, /shortages, /timeline, catalogue item/asset availability
8 Heavy computation Shortage resolution, fleet-wide availability, bulk imports/exports GET /warehouses/{id}/availability, POST /shortage_resolutions, POST /imports, POST /exports
20 Bulk availability grid One bounded read across many items and warehouses POST /availability/bulk

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 filter[field][operator] conditions and relation includes is weight 2, even when most callers page a small unfiltered set.

What is metered

Metering covers authenticated external traffic: requests to /api/v1 and calls made through the MCP server, including plugin-bridged MCP tools. PATs use their token budget; OAuth, stdio and CLI use their persisted connection budget. 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

MethodURLSummaryAbilityWeight
GET/api/v1/endpointsIndex endpointssystem:read0
GET/api/v1/request_logsIndex request logsapi-log:read0
GET/api/v1/usageIndex usageapi-usage:read0
GET/api/v1/usage/exportExport usageapi-usage:read0

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

Parameter Default Description
window 7d Date preset: 24h, 7d, 30d, or custom
from — Required when window=custom. Start date (Y-m-d)
to — Required when window=custom. End date (Y-m-d), must be on or after from
channel — Filter by metering channel: api, webhook_sent, or webhook_received
dimension endpoint Grouping: token, endpoint, resource, day, or status
token_id — Filter API-channel rows to a specific personal access token ID

Response

{
    "data": [
        {
            "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"
    }
}
Field Description
data[].key Group key — route name, token ID, resource name, date, or status class depending on dimension
data[].label Human label when available (e.g. token name for token dimension)
data[].request_count Total requests in the window
data[].weighted_units Sum of price weights (weight-0 traffic contributes 0)
meta.totals Window totals across all groups
meta.window Resolved date window

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

Request logs use filter[field][operator]=value; a scalar field value is shorthand for equality. Combine conditions with AND, and use timestamps with Z or an explicit offset for created_at. For example:

GET /api/v1/request_logs?filter[channel]=api&filter[status_code][eq]=200&filter[created_at][gte]=2026-07-01T00:00:00Z&filter[created_at][lt]=2026-07-02T00:00:00Z
Parameter Description
filter[route_name][eq]=api.v1.accounts.index Exact route name (API channel)
filter[status_code][eq]=200 HTTP status code
filter[personal_access_token_id][eq]=3 Token ID (API channel)
filter[channel][eq]=api Metering channel: api, webhook_sent, webhook_received
filter[created_at][gte]=2026-07-01T00:00:00Z Created on or after
filter[created_at][lte]=2026-07-01T00:00:00Z Created on or before

Unknown fields, unsupported operators, malformed values, and exceeded limits return 422 with unknown_filter_field, invalid_filter_operator, invalid_filter_value, or filter_limit_exceeded. See API Conventions for the complete grammar, list syntax, and limits.

Sorts

Parameter Description
sort=created_at Oldest first
sort=-created_at Newest first (default when sort omitted)
sort=status_code By status
sort=route_name By route name

Pagination

Offset pagination is the default: ?page=2&per_page=20. Use ?cursor=1&per_page=20 to start cursor paging, then pass meta.next_cursor or meta.prev_cursor unchanged. Cursor pages omit totals and page numbers. See pagination.

Response

{
    "data": [
        {
            "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,
        "last_page": 25
    }
}

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

{
    "data": [
        {
            "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

Channel Source Default units
api LogApiRequest middleware on /api/v1/* Endpoint #[PriceWeight]
webhook_sent DeliverWebhook job (first delivery attempt) 1 (per event via WebhookEventRegistry)
webhook_received InboundWebhookController (valid signature only) Source-configured weight (0–4)

Throughput headers

Read X-Signals-Units-Remaining, X-Signals-Units-Restore-Rate (units per minute), X-Signals-Units-Daily-Remaining and X-Signals-Units-Charged on metered responses. With enforcement enabled, 429 returns {"message":"Too Many Requests"} and Retry-After in seconds; wait before retrying. See rate limiting for conditional headers, zero-cost idempotent replays and the OpenAPI response components.