Realtime rating

Endpoint: POST /v1/ingest/usage

The realtime rating API accepts a usage event and publishes it to the tenant's billing pipeline. The event is ingested as a UsageEvent and rated asynchronously. Use Rated transactions to read the resulting transaction.

Authentication

Send a valid MPilot Bearer token. The token must contain:

tenantId — selects the tenant-specific usage topic.
morgId — used as the organization context for the usage event.

Submit a usage event

POST /v1/ingest/usage
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

curl -sS -X POST "https://YOUR_AI_GATEWAY_HOST/v1/ingest/usage" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "usage-event-001",
    "message": {
      "externalTransactionId": "usage-event-001",
      "serviceId": "e6cbd28a-f34c-482e-8da5-34e21dbd5eb7",
      "eventTimestamp": "2026-09-10T12:30:00Z",
      "billingAccountRef": "ACC-1001",
      "dimensions": {
        "Input_Tokens": "1000",
        "Output_Tokens": "250",
        "Model": "gpt-4o"
      },
      "quantity": 1250,
      "serviceInstanceId": "service-instance-001",
      "priceUnitLabel": "tokens"
    }
  }'

Request body

Field	Required	Description
`key`	No	Kafka record key. Using the external transaction ID is recommended.
`message`	Yes	Usage event submitted to the rating pipeline. Must be a JSON object.
`message.externalTransactionId`	Yes	Unique producer identifier for the usage event.
`message.serviceId`	Yes	UUID of the billing service to rate.
`message.eventTimestamp`	Yes	Time the usage occurred, in ISO 8601 format.
`message.billingAccountRef`	Yes	External ID of the billing account.
`message.dimensions`	Yes	Non-empty map of rating dimension names to string values. Names must match the service's configured dimensions.
`message.quantity`	No	Usage volume supplied to rating.
`message.serviceInstanceId`	No	External service-instance identifier.
`message.priceUnitLabel`	No	Price unit label associated with the usage.

externalTransactionId, serviceId, eventTimestamp, billingAccountRef, and a non-empty dimensions map are required by the downstream billing pipeline. Organization context comes from morgId in the token.

Response

Response 200

{
  "status": "published",
  "topic": "inference-usage_7d2f6c90-4b0a-4cf7-9c58-8f9e18f83a11",
  "partition": 3,
  "offset": 1842
}

A successful response confirms that Kafka accepted the event. Rating and persistence happen asynchronously; it does not confirm that the event was successfully rated.

Errors

{
  "is_bifrost_error": false,
  "status_code": 400,
  "error": {
    "message": "organizationId is required in the message or as morgId in the token"
  },
  "extra_fields": {}
}

Status	When
`400`	Invalid JSON, missing `message`, missing `morgId` in the token, or gateway Kafka configuration is unavailable.
`401`	Bearer token is missing, invalid, expired, or lacks `tenantId`.
`413`	Request body exceeds 1 MiB.
`502`	The gateway could not publish the event to Kafka.
`504`	Kafka publishing exceeded the request timeout.

Payload validation and account/service resolution happen downstream. Invalid events may be accepted by this endpoint and then skipped by the billing pipeline; use a unique externalTransactionId for tracking and retries.

Realtime rating

Realtime rating

Authentication

Submit a usage event

Request body

Response

Errors

On this page