The Scrums.com API is planned and not yet publicly available. Endpoints and behaviour are subject to change before release.
Overview
The Usage & Metering API exposes platform consumption data at the Service Line level. All metered usage on the Scrums.com platform is recorded against a LIN-* identifier. This data feeds directly into invoice generation at the end of each billing period.
Usage events are immutable. They are generated by the platform as talent hours are logged, agent runs execute, infrastructure resources operate, and intelligence queries are processed. You can query this data but cannot write to it directly via the metering API.
An exception is the POST /v1/metering/events endpoint, which allows trusted external systems to ingest usage events for custom integrations or hybrid billing arrangements.
Core Concepts
Meters
A meter defines a named consumption metric and its unit of measure. Platform meters are pre-defined per product line. Meters are the schema for usage events.
| Meter | Unit | Product line |
|---|
talent.hours | hours | Talent Marketplace, Managed Services |
talent.days | days | Talent Marketplace |
compute.vcpu_hours | vCPU-hours | Platforms & Infrastructure |
storage.gb_days | GB-days | Platforms & Infrastructure |
agent.runs | runs | AI Agent Gateway |
agent.tokens | tokens | AI Agent Gateway |
intelligence.queries | queries | Developer Intelligence |
ods.cycles | cycles | ODS |
Usage events
Each usage event records one unit of consumption: a time-stamped, metered quantity against a LIN-*. Events are append-only. They aggregate into the usage summary shown on Service Line billing responses.
Usage vs billing
Usage is raw consumption. Billing applies pricing rules (rate, plan commitments, overages) to usage to produce invoice line items. The metering API shows you raw usage; the Billing & Invoices API shows you what that usage costs.
Endpoints
GET /v1/usage
List usage records for an organization or workspace within a date range.
Request
GET /v1/usage?organization_id=ORG-26-090500&from=2026-04-01&to=2026-04-15&meter=talent.hours
Authorization: Bearer <token>
| Parameter | Type | Description |
|---|
organization_id | string | Scope to organization |
workspace_id | string | Scope to workspace |
service_line_id | string | Scope to a specific LIN-* |
meter | string | Filter by meter name |
from | date | Period start (inclusive) |
to | date | Period end (inclusive) |
cursor | string | Pagination cursor |
limit | integer | Results per page (max 100, default 25) |
Response
{
"data": [
{
"id": "USAGE-26-009812",
"service_line_id": "LIN-26-084729",
"meter": "talent.hours",
"quantity": 8.0,
"unit": "hours",
"recorded_at": "2026-04-14T18:00:00Z",
"period_date": "2026-04-14",
"source": "talent_timesheet",
"metadata": {
"talent_id": "SCR-128491",
"approved_by": "USR-26-000044"
}
}
],
"meta": {
"cursor": "eyJpZCI6IlVTQUdFLTI2LTAwOTgxMiJ9",
"has_more": true
}
}
GET /v1/usage/summary
Aggregated usage summary per Service Line over a period.
Request
GET /v1/usage/summary?organization_id=ORG-26-090500&from=2026-04-01&to=2026-04-30
Authorization: Bearer <token>
Response
{
"data": {
"period": {
"from": "2026-04-01",
"to": "2026-04-30"
},
"organization_id": "ORG-26-090500",
"total_cost_estimate": 298400.00,
"currency": "USD",
"by_service_line": [
{
"service_line_id": "LIN-26-084729",
"name": "Backend Engineering - Q2 2026",
"product_line": "talent",
"meters": [
{
"meter": "talent.hours",
"quantity": 640.0,
"unit": "hours"
}
],
"cost_estimate": 60800.00
},
{
"service_line_id": "LIN-26-091100",
"name": "Agent Gateway - Production",
"product_line": "agent_gateway",
"meters": [
{
"meter": "agent.runs",
"quantity": 4811,
"unit": "runs"
},
{
"meter": "agent.tokens",
"quantity": 9482000,
"unit": "tokens"
}
],
"cost_estimate": 7240.00
}
]
}
}
GET /v1/meters
List all available meters with their units and applicable product lines.
Response
{
"data": [
{
"id": "talent.hours",
"name": "Talent Hours",
"unit": "hours",
"product_lines": ["talent", "managed_services"],
"description": "Billable hours logged by allocated talent resources."
},
{
"id": "agent.runs",
"name": "Agent Runs",
"unit": "runs",
"product_lines": ["agent_gateway"],
"description": "Number of completed agent execution runs."
}
]
}
POST /v1/metering/events
Ingest external usage events for hybrid billing or custom integrations.
Request
{
"service_line_id": "LIN-26-084729",
"meter": "talent.hours",
"quantity": 8.0,
"period_date": "2026-04-14",
"idempotency_key": "timesheet-SCR-128491-20260414",
"metadata": {
"talent_id": "SCR-128491",
"approved_by": "USR-26-000044"
}
}
Response
{
"data": {
"id": "USAGE-26-009812",
"status": "accepted",
"service_line_id": "LIN-26-084729",
"meter": "talent.hours",
"quantity": 8.0,
"recorded_at": "2026-04-15T10:00:00Z"
}
}
Notes
idempotency_key prevents duplicate event ingestion. Resubmitting the same key within 48 hours returns the original event record.- External ingestion requires the API key to have the
metering:write scope.
- Only meters permitted by the Service Line’s billing model are accepted.
Common Workflows
Monthly usage reconciliation
# Summary across all service lines for the billing period
GET /v1/usage/summary?organization_id=ORG-26-090500&from=2026-04-01&to=2026-04-30
# Drill into a specific service line
GET /v1/usage?service_line_id=LIN-26-084729&from=2026-04-01&to=2026-04-30
# Verify event-level detail if totals look unexpected
GET /v1/usage?service_line_id=LIN-26-084729&from=2026-04-01&to=2026-04-30&meter=talent.hours
Objects
Usage event
| Field | Type | Description |
|---|
id | string | Event identifier (USAGE-*) |
service_line_id | string | Source LIN-* |
meter | string | Meter name |
quantity | number | Measured quantity |
unit | string | Unit of measure |
period_date | date | The date the usage applies to |
recorded_at | datetime | When the event was recorded |
source | string | System that generated the event |
metadata | object | Source-specific supplementary data |
Best Practices
- Use
service_line_id filtering as your primary lens. Usage queries without a service_line_id or workspace_id filter across the entire organization. For large orgs with many Service Lines, always filter.
- Use
idempotency_key on all POST /v1/metering/events calls. External systems frequently retry on network failure. Without an idempotency key, retries create duplicate usage records that inflate invoices.
- Cross-check usage summaries against invoice line items. Usage summaries show raw consumption; invoices apply pricing. The numbers will differ when plan commitments, volume discounts, or overages apply.
