Usage & Metering

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>

Query parameters

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.

Overview

Organizations

Workspaces

Service Lines

Core Platform

Observability & Metrics

ODS

Talent Marketplace

AI Agent Gateway

Product Lines

CLI

Overview

Core Concepts

Meters

Usage events

Usage vs billing

Endpoints

GET /v1/usage

Request

Response

GET /v1/usage/summary

Request

Response

GET /v1/meters

Response

POST /v1/metering/events

Request

Response

Notes

Common Workflows

Monthly usage reconciliation

Objects

Usage event

Best Practices

​Overview

​Core Concepts

​Meters

​Usage events

​Usage vs billing

​Endpoints

​GET /v1/usage

​Request

​Response

​GET /v1/usage/summary

​Request

​Response

​GET /v1/meters

​Response

​POST /v1/metering/events

​Request

​Response

​Notes

​Common Workflows

​Monthly usage reconciliation

​Objects

​Usage event

​Best Practices

Overview

Core Concepts

Meters

Usage events

Usage vs billing

Endpoints

GET /v1/usage

Request

Response

GET /v1/usage/summary

Request

Response

GET /v1/meters

Response

POST /v1/metering/events

Request

Response

Notes

Common Workflows

Monthly usage reconciliation

Objects

Usage event

Best Practices