Metering

Emit usage metering events for tracking consumption and feeding the billing pipeline.

The metering API records usage events that feed downstream billing aggregation. Metering is a separate layer from billing - it records what happened, not what to charge. The billing layer prices metered events according to customer-specific rules.

Emit a Metering Event

POST /v1/{workspace_id}/metering/emit

Emit one usage event for the calling workspace. Returns 202 on success. Emission is fire-and-forget with no built-in deduplication.

Request Body

Field	Type	Required	Description
event_type	string	Yes	Free-form event type identifier. Lowercase, 1-64 characters, must match ^[a-z][a-z0-9._]*$. Examples: pdf_pages_processed, minutes.transcribed.
metering_quantity	number	Yes	Numeric quantity (zero or positive).
metering_unit	string	No	What the quantity represents (e.g., pages, minutes, tokens). Max 32 characters.
metering_metadata	object	No	Optional key-value pairs for audit context and dispute resolution.

Response

202 Accepted

{
  "status": "accepted",
  "event_type": "pdf_pages_processed"
}

422 Unprocessable Entity - returned when the request shape is invalid (bad event_type pattern, negative quantity, etc.). The response body contains the specific validation error.

Example

curl -X POST https://api.platform.amigo.ai/v1/{workspace_id}/metering/emit \
  -H "Authorization: Bearer $AMIGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "pdf_pages_processed",
    "metering_quantity": 12,
    "metering_unit": "pages",
    "metering_metadata": {"document_id": "abc-123"}
  }'

SDK Usage

From External Environments (Laptops, Notebooks, CI)

For code running outside platform services, use the synchronous metering client. It posts to the HTTP endpoint using a workspace API key - no infrastructure credentials required.

Environment variables:

Variable	Required	Description
AMIGO_API_KEY	Yes (unless passed as parameter)	Workspace API key
AMIGO_PLATFORM_URL	No	Platform API base URL override (defaults to production)

Example:

from platform_lib.metering.client import emit

emit(
    workspace_id="your-workspace-id",
    event_type="pdf_pages_processed",
    metering_quantity=12,
    metering_unit="pages",
    metering_metadata={"document_id": "abc-123"},
)

The client raises an error when AMIGO_API_KEY is not set and no api_key parameter is provided. Non-2xx responses raise an HTTP error with the response body containing the specific reason.

From Platform Services (In-Process)

For code running inside a platform service with a wired event emitter, use the async metering helper. It emits directly without an HTTP round-trip.

from platform_lib.metering import metering_emit

await metering_emit(
    emitter,
    workspace_id=workspace_id,
    event_type="pdf_pages_processed",
    metering_quantity=12,
    metering_unit="pages",
    metering_metadata={"document_id": "abc-123"},
)

Passing emitter=None is a safe no-op, useful in tests or during early startup before the emitter is available.

Event Type Naming

Event types are free-form lowercase strings. Use descriptive, dot-separated names that identify the domain and action:

• pdf_pages_processed

• minutes.transcribed

• tokens.consumed

Reuse existing event type names where possible. New event types are accepted without registration - they land in the event log and become available for aggregation when a corresponding aggregation rule is configured.

Idempotency

Metering emission is fire-and-forget with no built-in deduplication key. If you add retry logic around an emit call and a retry succeeds after the server also processed the first attempt, the event is recorded twice. Handle idempotency at your call site by tracking what you have already emitted.