Skip to main content
POST
/
sessions
/
metering
Report Session Metering
curl --request POST \
  --url https://api.mulerun.com/sessions/metering \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "agentId": "123e4567-e89b-12d3-a456-426614174000",
  "sessionId": "987e6543-e21b-45cd-b678-123456789abc",
  "cost": 1050,
  "timestamp": "2023-10-27T10:00:00Z",
  "isFinal": false,
  "meteringId": "abc123efg-456h-789i-jklm-123nop456qr"
}
'
{
  "status": "success",
  "meteringId": "abc123efg-456h-789i-jklm-123nop456qr"
}

Documentation Index

Fetch the complete documentation index at: https://mulerun.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

This API is used by agents to report usage costs for billing purposes. It supports idempotent metering with automatic deduplication.

​
Idempotency Mechanism

  • New meteringId: The request is processed and stored. A success response is returned.
  • Duplicate meteringId: The system returns the cached response without reprocessing.
  • This ensures safe retries without double billing.

​
Additional Billing & Session Rules

​
1. Timestamp Ordering

  • All metering reports must have monotonically increasing timestamp values.
  • Out-of-order reports may be rejected or handled with warnings during auditing.

​
2. Final State Idempotency

  • Once a report with "isFinal": true is accepted for a sessionId, the session is marked as completed.
  • Any further reports for the same sessionId will be ignored (cached response returned).

​
3. Session Termination Handling

  • No Reports Received: If no metering reports are sent, MuleRun will charge based on internal resource tracking.
  • Grace Period: If no final report is received before session end, late reports are accepted within 1 minute after termination.
  • Abnormal Termination: In cases of crash or forced termination, the grace period does not apply — charges are settled immediately.

​
4. Negative Credit Balance

  • If a user’s credit balance becomes negative, the session is immediately terminated.
  • All subsequent metering reports for that session will be ignored.

​
Authentication

Authentication is done using your Agent Key as a Bearer token in the Authorization header.

​
Best Practices

  • Generate a new UUIDv4 for each meteringId to ensure idempotency.
  • Always send a final report with "isFinal": true when the session completes normally.
  • Ensure timestamps are monotonically increasing for sequential reports.

Authorizations

​
Authorization
string
header
required

Use your Agent Key as the Bearer token

Body

application/json
​
agentId
string<uuid>
required

Unique ID assigned by MuleRun to identify the agent.

Example:

"123e4567-e89b-12d3-a456-426614174000"

​
sessionId
string<uuid>
required

Identifier for the current user session. Multiple reports with the same sessionId belong to the same session.

Example:

"987e6543-e21b-45cd-b678-123456789abc"

​
cost
integer
required

Usage cost in units of 0.0001 credits. For example, 1050 = 0.105 credits. Must be positive.

Required range: x >= 1
Example:

1050

​
timestamp
string<date-time>
required

UTC timestamp indicating when this usage was recorded.

Example:

"2023-10-27T10:00:00Z"

​
meteringId
string<uuid>
required

A globally unique idempotency key. Prevents duplicate processing of the same report. UUID v4 recommended.

Example:

"abc123efg-456h-789i-jklm-123nop456qr"

​
isFinal
boolean
default:false

If true, marks this as the final report for the session (AND session will be terminated). Defaults to false.

Example:

false

Response

Success response

​
status
enum<string>

Status of the request

Available options:
success
Example:

"success"

​
meteringId
string

The idempotency key stored by MuleRun for this record.

Example:

"abc123efg-456h-789i-jklm-123nop456qr"