Skip to main content

​
Overview

Opsmatic tracks AI usage and cost from two sources:

OpenClaw (automatic)

The OpenClaw daemon pushes token usage and costs with every heartbeat — no API calls needed. See the OpenClaw setup guide for how those costs are calculated.

Usage API (this page)

For n8n, Make.com, and custom workloads, your workflows report token usage and cost estimates themselves via POST /v1/usage — typically from an HTTP Request node at the end of an AI workflow.
The Usage API lets you attribute AI spend to the workflows and executions that produced it, then query it back raw or aggregated.

​
Authentication & Permissions

All endpoints use a standard API key (Authorization: Bearer ops_...). The key needs:
OperationRequired permission
POST /v1/usageusage: write
GET /v1/usage, PUT /v1/usageusage: read
The key must also have access to the connection each entry references — personal keys cover your own connections and those of organizations you belong to.

​
Push Usage Entries

POST /v1/usage
Accepts a single entry or a batch (array, max 100 entries per request).

​
Entry Fields

FieldTypeRequiredDescription
connection_idstringYesThe Opsmatic connection this usage belongs to (e.g. your n8n connection)
entitystringYesWhat consumed the usage — a model name (gpt-4o), service, or component
usage_amountnumberYesThe quantity consumed — token count for tokens entries
usage_entitytokens | customNoDefaults to tokens. Use custom with custom_name for non-token units (API calls, minutes, images)
custom_namestringWith customName of the custom unit being counted
cost_centsnumberNoCost estimate in cents (e.g. 12 = $0.12). Defaults to 0
workflow_idstringNoThe n8n/Make workflow that produced the usage
execution_idstringNoThe specific execution, for per-run attribution
metadataobjectNoAny extra context (model parameters, user, environment)

​
Example — single entry

curl -X POST https://api.opsmatic.com/v1/usage \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "connection_id": "conn_abc123",
    "workflow_id": "wf_support_triage",
    "execution_id": "exec_20260706_1432",
    "entity": "gpt-4o",
    "usage_entity": "tokens",
    "usage_amount": 4820,
    "cost_cents": 3,
    "metadata": { "prompt_tokens": 3900, "completion_tokens": 920 }
  }'

​
Example — batch

curl -X POST https://api.opsmatic.com/v1/usage \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    { "connection_id": "conn_abc123", "entity": "gpt-4o", "usage_amount": 4820, "cost_cents": 3 },
    { "connection_id": "conn_abc123", "entity": "claude-sonnet-4-5", "usage_amount": 12100, "cost_cents": 9 }
  ]'
Responses return 201 with the inserted entries. Validation failures return 400 with a per-index validation_errors array — in a batch, one invalid entry rejects the whole request, so fix and resend.

​
Reporting Token Usage from n8n

The recommended pattern: add an HTTP Request node after your AI/LLM node and map the token usage the node already exposes.
1

Capture token counts from the AI node

Most n8n AI nodes (OpenAI, Anthropic, AI Agent) return token usage in their output — typically under tokenUsage or usage with prompt/completion/total token counts. Check your node’s output panel for the exact path.
2

Estimate the cost

Multiply tokens by your model’s rates. Example expression for GPT-4o (2.50/Minput,2.50/M input, 10/M output), producing cents:
{{ Math.round(($json.tokenUsage.promptTokens * 2.50 + $json.tokenUsage.completionTokens * 10.00) / 1000000 * 100) }}
3

Add an HTTP Request node

  • Method: POST
  • URL: https://api.opsmatic.com/v1/usage
  • Authentication: Header Auth — Authorization: Bearer YOUR_API_KEY
  • Body (JSON):
{
  "connection_id": "conn_abc123",
  "workflow_id": "{{ $workflow.id }}",
  "execution_id": "{{ $execution.id }}",
  "entity": "gpt-4o",
  "usage_entity": "tokens",
  "usage_amount": "{{ $json.tokenUsage.totalTokens }}",
  "cost_cents": "{{ Math.round(($json.tokenUsage.promptTokens * 2.50 + $json.tokenUsage.completionTokens * 10.00) / 1000000 * 100) }}",
  "metadata": {
    "prompt_tokens": "{{ $json.tokenUsage.promptTokens }}",
    "completion_tokens": "{{ $json.tokenUsage.completionTokens }}"
  }
}
4

Verify in Opsmatic

Entries appear in the connection’s usage data immediately — query them with GET /v1/usage?connection_id=conn_abc123 or view them in Analytics.
Use {{ $workflow.id }} and {{ $execution.id }} so every entry is attributable to the exact run that spent the tokens — that’s what makes per-workflow cost breakdowns possible later.
If your workflow calls multiple models, send a batch with one entry per model rather than a single summed entry — per-model attribution is lost once counts are merged.

​
Query Usage Entries

GET /v1/usage
Returns raw entries, newest first, scoped to connections your key can access.

​
Query Parameters

ParameterDescription
connection_idFilter to one connection
workflow_idFilter to one workflow
execution_idFilter to one execution
entityFilter by entity (e.g. gpt-4o)
usage_entitytokens or custom
start_date / end_dateISO timestamps bounding created_at
limitPage size, max 100 (default 50)
offsetPagination offset
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.opsmatic.com/v1/usage?connection_id=conn_abc123&usage_entity=tokens&start_date=2026-07-01T00:00:00Z"
Response: 
{
  "usage_data": [
    {
      "connection_id": "conn_abc123",
      "workflow_id": "wf_support_triage",
      "execution_id": "exec_20260706_1432",
      "entity": "gpt-4o",
      "usage_entity": "tokens",
      "usage_amount": 4820,
      "cost_cents": 3,
      "created_at": "2026-07-06T14:32:11Z"
    }
  ],
  "pagination": { "total": 1, "limit": 50, "offset": 0, "has_more": false }
}

​
Aggregated Summaries

PUT /v1/usage?connection_id=conn_abc123
Returns rolled-up totals instead of raw entries. connection_id is required.
  • Connection summary — pass connection_id alone (optionally start_date / end_date; defaults to the last 30 days) for totals across the connection.
  • Execution summary — pass workflow_id and execution_id for the totals of a single run.
# What did this specific execution cost?
curl -X PUT -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.opsmatic.com/v1/usage?connection_id=conn_abc123&workflow_id=wf_support_triage&execution_id=exec_20260706_1432"

OpenClaw Cost Tracking

Automatic token and cost monitoring for OpenClaw gateways, including budget alerts

API Introduction

Authentication, rate limits, and error handling for all API endpoints