Usage Events

A usage event is a single measurement — “at this time, this customer used this agent to do this much of this thing.” Logging usage events is how MarginFront learns what to bill for. Every time your agent does work, you log an event. At the end of the billing period, MarginFront rolls them up, applies the customer’s pricing plan, and generates an invoice. This is the most important endpoint in the whole API. Everything else (agents, signals, plans, subscriptions) is setup. This is the ongoing, every-day traffic.

The endpoint

POST /v1/usage/record

Authentication: API key in the X-API-Key header (secret key required — mf_sk_*). Batch: Even for a single event, the body wraps records in an array. You can send 1-100 records per request.

{
  "records": [
    { ...one usage event... },
    { ...another usage event... }
  ]
}

Fields per record

Required fields

Field	Type	Description
`customerExternalId`	string	Your customer’s ID in your system. The `externalId` you set when you created the customer (not the internal UUID). Example: `"acme-001"`.
`agentCode`	string	The agent/product code from the dashboard. Example: `"cs-bot-v2"`.
`signalName`	string	The metric being tracked. Usually matches the signal’s `shortName`. Example: `"messages"`.
`model`	string	The model identifier from your provider. Pass whatever your provider SDK returned: `response.model` from OpenAI/Anthropic, the service SKU for non-LLM tools. Case-insensitive, whitespace trimmed. Examples: `"gpt-4o"`, `"claude-sonnet-4-6"`, `"twilio-sms"`, `"textract-standard"`.
`modelProvider`	string	The provider name, lowercase. This tells MarginFront which pricing table to look in. Required because different providers can have models with the same name — without this field, MarginFront can’t tell if `"gpt-4o"` means OpenAI’s or a fine-tune on another platform. Examples: `"openai"`, `"anthropic"`, `"google"`, `"twilio"`, `"aws"`.

Optional fields

Field	Type	Default	Description
`inputTokens`	integer (≥ 0)	—	Number of input (prompt) tokens. Required for LLM cost calculation. Ignored for non-LLM services.
`outputTokens`	integer (≥ 0)	—	Number of output (completion) tokens. Required for LLM cost calculation. Ignored for non-LLM services.
`quantity`	integer (≥ 0)	`1`	Number of billing units for non-LLM services (pages processed, SMS sent, API calls, etc.).
`usageDate`	ISO 8601 string	now	When the usage actually happened. Use this for back-filling historical events.
`metadata`	object	`{}`	Custom key-value pairs. Stored but not interpreted.

LLM vs non-LLM events

Both patterns use the same endpoint. The difference is which fields carry the “how much” information. LLM event (OpenAI, Anthropic, Google, etc.) — cost is based on tokens:

{
  "customerExternalId": "acme-001",
  "agentCode": "cs-bot-v2",
  "signalName": "messages",
  "model": "gpt-4o",
  "modelProvider": "openai",
  "inputTokens": 523,
  "outputTokens": 117
}

Non-LLM event (Twilio, AWS Textract, DALL-E, etc.) — cost is based on quantity:

{
  "customerExternalId": "acme-001",
  "agentCode": "notification-agent",
  "signalName": "sms_sent",
  "model": "twilio-sms",
  "modelProvider": "twilio",
  "quantity": 3
}

You can mix both types in a single batch.

Example curl calls

Single LLM event (OpenAI):

curl -X POST https://api.marginfront.com/v1/usage/record \
  -H "X-API-Key: mf_sk_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "records": [
      {
        "customerExternalId": "acme-001",
        "agentCode": "cs-bot-v2",
        "signalName": "messages",
        "model": "gpt-4o",
        "modelProvider": "openai",
        "inputTokens": 523,
        "outputTokens": 117
      }
    ]
  }'

Single LLM event (Anthropic):

curl -X POST https://api.marginfront.com/v1/usage/record \
  -H "X-API-Key: mf_sk_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "records": [
      {
        "customerExternalId": "acme-001",
        "agentCode": "research-agent",
        "signalName": "research_queries",
        "model": "claude-sonnet-4-6",
        "modelProvider": "anthropic",
        "inputTokens": 1024,
        "outputTokens": 512
      }
    ]
  }'

Non-LLM event (Twilio SMS):

curl -X POST https://api.marginfront.com/v1/usage/record \
  -H "X-API-Key: mf_sk_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "records": [
      {
        "customerExternalId": "acme-001",
        "agentCode": "notification-agent",
        "signalName": "sms_sent",
        "model": "twilio-sms",
        "modelProvider": "twilio",
        "quantity": 5
      }
    ]
  }'

Mixed batch (3 events):

curl -X POST https://api.marginfront.com/v1/usage/record \
  -H "X-API-Key: mf_sk_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "records": [
      {"customerExternalId": "acme-001", "agentCode": "cs-bot-v2", "signalName": "messages", "model": "gpt-4o", "modelProvider": "openai", "inputTokens": 100, "outputTokens": 50},
      {"customerExternalId": "acme-001", "agentCode": "cs-bot-v2", "signalName": "messages", "model": "claude-sonnet-4-6", "modelProvider": "anthropic", "inputTokens": 200, "outputTokens": 75},
      {"customerExternalId": "beta-corp", "agentCode": "doc-analyzer", "signalName": "pages_processed", "model": "textract-standard", "modelProvider": "aws", "quantity": 15}
    ]
  }'

Response format (`200 OK`)

The endpoint always returns 200 OK — even if some records failed. You must check the response body to know what actually happened.

{
  "processed": 3,
  "successful": 2,
  "failed": 1,
  "results": {
    "success": [
      {
        "customerExternalId": "acme-001",
        "agentCode": "cs-bot-v2",
        "signalName": "messages",
        "model": "gpt-4o",
        "modelProvider": "openai",
        "inputTokens": 523,
        "outputTokens": 117,
        "quantity": 1,
        "totalCostUsd": "0.0024780000",
        "eventId": "8a7b6c5d-...",
        "rawEventId": "f1e2d3c4-...",
        "timestamp": "2026-04-12T20:10:54.218Z"
      }
    ],
    "failed": [
      {
        "record": {
          "customerExternalId": "acme-001",
          "model": "my-custom-llm",
          "modelProvider": "custom",
          "...": "..."
        },
        "code": "NEEDS_COST_BACKFILL",
        "stored": true,
        "eventId": "a1b2c3d4-...",
        "rawEventId": "e5f6g7h8-...",
        "error": "Model \"my-custom-llm\" (provider \"custom\") not found in service_pricing. Event stored — map this model in the dashboard."
      }
    ]
  }
}

Success entry fields

Field	Description
`customerExternalId`	Echoed from your request
`agentCode`	Echoed from your request
`signalName`	Echoed from your request
`model` / `modelProvider`	Echoed from your request
`inputTokens` / `outputTokens`	Echoed from your request
`quantity`	Echoed (or `1` if you didn’t send it)
`totalCostUsd`	Calculated cost in USD (string with 10 decimal places)
`eventId`	UUID of the `signal_events` row — use this for lookups
`rawEventId`	UUID of the `raw_ingest_events` audit row
`timestamp`	When the event was processed

Failed entry fields

Field	Description
`record`	The original record you sent (echoed back so you can identify it)
`code`	Why it failed: `NEEDS_COST_BACKFILL`, `INTERNAL_ERROR`, or `VALIDATION_ERROR`
`stored`	`true` = event is saved in the system (don’t retry). `false` = event was NOT saved (safe to retry).
`eventId`	UUID of the signal_events row (only present when `stored: true`)
`rawEventId`	UUID of the raw audit row (present for most failures)
`error`	Human-readable description of what happened

Error codes explained

Code	Stored?	What happened	What to do
`NEEDS_COST_BACKFILL`	Yes	The model+provider combination isn’t in the pricing table. The event is saved with `cost: null`.	Do NOT retry. Go to the MarginFront dashboard → Usage Events → “Needs attention” and map the model to a known one. Once mapped, cost is backfilled automatically and all future events with that model auto-resolve.
`INTERNAL_ERROR`	No	Something broke on our side during processing. The event was not saved to signal_events.	Safe to retry. The raw audit row may exist (check `rawEventId`).
`VALIDATION_ERROR`	No	Bad input — a required field is missing or has the wrong type.	Fix the request and resend. Check the `error` message for which field.

What happens when the model isn’t recognized

MarginFront never drops events. If you send a model + modelProvider combination that isn’t in the pricing table:

The event is stored in signal_events with usageCost: null (not zero — null preserves the ambiguity for backfill).
The response includes the event in results.failed[] with code: "NEEDS_COST_BACKFILL" and stored: true.
The “Needs attention” tile on the dashboard /metrics-events page shows a count of these events.
Click through to see the events grouped by model+provider, with context (which agent, customer, signal sent them).
Pick a known model from the dropdown, click “Map & backfill” — MarginFront creates a permanent mapping and retroactively calculates cost for every affected event.
Future events with that model+provider auto-resolve — no manual step needed again.

Do NOT retry events with stored: true. They’re already in the system. Retrying would create duplicates.

Mapping unknown models (API endpoints)

These endpoints power the dashboard drill-down page. You can also call them directly.

List unknown-cost event groups

GET /v1/events/needs-cost-backfill

Query parameters (all optional):

Param	Type	Default	Description
`startDate`	ISO 8601	30 days ago	Filter events after this date
`endDate`	ISO 8601	now	Filter events before this date

Response:

{
  "groups": [
    {
      "model": "my-custom-llm",
      "provider": "custom",
      "count": 3,
      "oldestEventDate": "2026-04-11T22:12:14.000Z"
    }
  ],
  "totalEvents": 3
}

Map an unknown model to a known one

POST /v1/events/map-model

Request body:

{
  "sourceModel": "my-custom-llm",
  "sourceProvider": "custom",
  "targetPricingId": "550e8400-e29b-41d4-a716-446655440000"
}

Or use model+provider to identify the target instead of the pricing row ID:

{
  "sourceModel": "my-custom-llm",
  "sourceProvider": "custom",
  "targetModel": "gpt-4o",
  "targetProvider": "openai"
}

Response:

{
  "backfilled": 3,
  "mappingId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

This creates an org-scoped mapping for the source model (so future events auto-resolve for this org) and retroactively calculates cost for all matching events in a single transaction.

Listing events

Query your recorded usage events. Supports filtering and pagination. Use this when you need to see individual events — per-event drill-downs, audit trails, debugging a specific customer’s bill, or feeding a BI tool.

GET /v1/events

Authentication: x-api-key header. Either a secret key (mf_sk_*) or a publishable key (mf_pk_*) works — this is a read-only endpoint.

Query parameters

All optional. Without any, you get the most recent 20 events for your org.

Param	Type	Default	Description
`page`	integer (≥ 1)	`1`	Page number.
`limit`	integer (1-100)	`20`	Results per page. Capped at 100.
`customerId`	UUID	—	Filter to events for one customer. Use MarginFront’s internal customer UUID (not your `externalId`).
`agentId`	UUID	—	Filter to events for one agent.
`signalId`	UUID	—	Filter to events for one signal.
`startDate`	ISO 8601 string	—	Only events on or after this timestamp.
`endDate`	ISO 8601 string	—	Only events on or before this timestamp.

Example

curl "https://api.marginfront.com/v1/events?customerId=bc8eceda-50e4-4138-b2a2-47e92d344540&limit=20" \
  -H "x-api-key: mf_sk_test_YOUR_KEY"

Response (`200 OK`)

{
  "results": [
    {
      "id": "b137e553-d67e-4a85-8e34-d67522c02752",
      "customerExternalId": "acme-001",
      "customerId": "bc8eceda-50e4-4138-b2a2-47e92d344540",
      "subscriptionId": null,
      "organizationId": "d2c03528-67db-4e2f-9986-88c11998b46f",
      "agentId": "3a1948ea-a701-4752-8c3d-df6c2f5833cf",
      "signalId": "9ab845c3-0d35-42ca-86cf-58c886af883c",
      "rawIngestEventId": "2e038dba-7875-4c67-8f32-f89d3b3d7c9f",
      "usageDate": "2026-04-14T18:44:53.075Z",
      "quantity": "1",
      "metadata": {},
      "usageCost": "0.00225",
      "usageCostData": {
        "gpt-4o/input": {
          "cost": 0.00125,
          "units": 500,
          "costPerUnit": 0.0000025
        },
        "gpt-4o/output": {
          "cost": 0.001,
          "units": 100,
          "costPerUnit": 0.00001
        }
      },
      "eventProcessed": "PROCESSED",
      "eventProcessedAt": "2026-04-14T18:44:54.263Z",
      "createdAt": "2026-04-14T18:44:53.075Z",
      "updatedAt": "2026-04-14T18:44:53.075Z",
      "signal": {
        "id": "9ab845c3-0d35-42ca-86cf-58c886af883c",
        "name": "Messages Processed",
        "shortName": "messages"
      }
    }
  ],
  "page": 1,
  "limit": 20,
  "totalPages": 42,
  "totalResults": 837
}

Understanding the event payload

Most fields are self-explanatory. A few are easy to trip over:

usageCost is a string, not a number (e.g. "0.00225"). We use strings to preserve decimal precision — prices can have many significant digits and JSON numbers would round. Convert with parseFloat() or Number() before doing math.
usageCostData is the itemized cost breakdown — this is where per-model and per-dimension details live. Each key is "<model>/<dimension>" (e.g. "gpt-4o/input", "gpt-4o/output"). Each value has:
- cost — dollar amount for this line item (number)
- units — tokens for LLMs, or whatever quantity dimension was billed (number)
- costPerUnit — the rate applied (number)
The top-level usageCost equals the sum of every cost inside usageCostData. If you need to ask “how many input tokens did this event use?”, read usageCostData["<model>/input"].units. If the event used multiple models or mixed LLM+non-LLM services, there will be multiple keys.
quantity is a string (same precision reason as usageCost).
signal is the nested signal object (id, name, shortName). Handy for display without a second lookup.
subscriptionId is null when the customer had no active subscription at the time of the event.

Event processing states

The eventProcessed field tells you where an event is in its lifecycle:

Value	Meaning
`"PROCESSED"`	Cost calculated and stored. Ready to be included in invoices.
`"NEEDS_COST_BACKFILL"`	Event stored but cost is `null` — the model+provider wasn’t found in the pricing table. Use `GET /v1/events/needs-cost-backfill` to find these and `POST /v1/events/map-model` to resolve.
`"PENDING"`	Still being processed. Should transition within seconds.
`"ERROR"`	Cost calculation failed for a reason other than an unknown model. Rare — inspect the event in the dashboard.

When eventProcessed is "NEEDS_COST_BACKFILL", usageCost is null and usageCostData is empty. See Mapping unknown models above for the resolution flow.

Auto-provisioning

If you log a usage event for a customerExternalId or agentCode that MarginFront has never seen, it will auto-create a minimal customer and/or agent on the spot. Convenient for prototyping — but means you won’t get an error for typos. Double-check in the dashboard if things “work” but show up with a name you don’t recognize.

Common HTTP errors

Status	Cause
`400 Bad Request`	The batch is empty, has more than 100 records, or a record is missing a required field (`customerExternalId`, `agentCode`, `signalName`, `model`, or `modelProvider`). The response body tells you which field.
`401 Unauthorized`	API key is missing or invalid.
`403 Forbidden`	You used a publishable key (`mf_pk_`). Usage recording requires a secret key (`mf_sk_`).

Using the Node SDK

The @marginfront/sdk package wraps this endpoint. See the SDK README for full documentation. Quick example:

import { MarginFrontClient } from "@marginfront/sdk";

const client = new MarginFrontClient("mf_sk_test_YOUR_KEY");

// Single LLM event
await client.usage.record({
  customerExternalId: "acme-001",
  agentCode: "cs-bot-v2",
  signalName: "messages",
  model: "gpt-4o",
  modelProvider: "openai",
  inputTokens: 523,
  outputTokens: 117,
});

// Batch
await client.usage.recordBatch([
  {
    customerExternalId: "acme-001",
    agentCode: "cs-bot-v2",
    signalName: "messages",
    model: "gpt-4o",
    modelProvider: "openai",
    inputTokens: 100,
    outputTokens: 50,
  },
  {
    customerExternalId: "beta-corp",
    agentCode: "doc-analyzer",
    signalName: "pages_processed",
    model: "textract-standard",
    modelProvider: "aws",
    quantity: 15,
  },
]);

With the default fireAndForget: true setting, usage.record() never throws — network errors retry automatically via a local buffer. See the SDK docs for details.

When to log events

Log an event right after the work is done. The sooner MarginFront sees it, the sooner it shows up in analytics and cost projections. For high-volume scenarios, the SDK handles batching and retries automatically with its built-in buffer. If you’re calling the REST API directly, batch up to 100 records per request and send them every few seconds.

Resources

Reference

Usage Events

Usage Events

The endpoint

Fields per record

Required fields

Optional fields

LLM vs non-LLM events

Example curl calls

Response format (`200 OK`)

Success entry fields

Failed entry fields

Error codes explained

What happens when the model isn’t recognized

Mapping unknown models (API endpoints)

List unknown-cost event groups

Map an unknown model to a known one

Listing events

Query parameters

Example

Response (`200 OK`)

Understanding the event payload

Event processing states

Auto-provisioning

Common HTTP errors

Using the Node SDK

When to log events

Resources

Reference

​Usage Events

​The endpoint

​Fields per record

​Required fields

​Optional fields

​LLM vs non-LLM events

​Example curl calls

​Response format (200 OK)

​Success entry fields

​Failed entry fields

​Error codes explained

​What happens when the model isn’t recognized

​Mapping unknown models (API endpoints)

​List unknown-cost event groups

​Map an unknown model to a known one

​Listing events

​Query parameters

​Example

​Response (200 OK)

​Understanding the event payload

​Event processing states

​Auto-provisioning

​Common HTTP errors

​Using the Node SDK

​When to log events

Usage Events

The endpoint

Fields per record

Required fields

Optional fields

LLM vs non-LLM events

Example curl calls

Response format (`200 OK`)

Success entry fields

Failed entry fields

Error codes explained

What happens when the model isn’t recognized

Mapping unknown models (API endpoints)

List unknown-cost event groups

Map an unknown model to a known one

Listing events

Query parameters

Example

Response (`200 OK`)

Understanding the event payload

Event processing states

Auto-provisioning

Common HTTP errors

Using the Node SDK

When to log events