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"
}
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"