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
| Method | URL | Summary | Ability | Weight |
|---|---|---|---|---|
GET | /api/v1/endpoints | Index endpoints | system:read | 0 |
GET | /api/v1/request_logs | Index request logs | api-log:read | 0 |
GET | /api/v1/usage | Index usage | api-usage:read | 0 |
GET | /api/v1/usage/export | Export usage | api-usage:read | 0 |
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) |
Related documentation
- API Console (platform) — Explorer, Request Log, Usage dashboard, and Webhooks UI
- Webhooks — outbound subscriptions and inbound receiver
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.