Managed services & budgets

Every instance is created with managed credentials for four services: the LLM router, web search (Brave), app integrations (Composio), and paid tools (Perflo). Managed calls route and meter through Agent37, so there are no provider or integration keys for you to manage. See Managed services for HTTP and MCP examples, including custom-image setup. Each paid managed call is metered at cost against your workspace wallet, and a per-instance budget caps how much each instance can spend.

Rates

Service	Rate
Managed LLM	OpenRouter inference cost, passed through with no Agent37 markup
Web search (Brave)	$0.005 per call (5,000 micros)
Composio	$0.000114 per call (114 micros)
Perflo paid tools	Reported charge, passed through with no markup; discovery is free

All money fields are integer micros: USD x 1,000,000, so $1.00 is 1000000. Managed spend debits the workspace wallet, the same wallet that pays for compute. Top it up at agent37.com/dashboard/cloud/billing.

The managed model

Those credentials reach the agent as environment variables on the instance, which is what makes them work in a custom image too. The instance’s starter token, AGENT37_MANAGED_TOKEN, authorizes managed-service calls that spend wallet credit within this budget. Your sk_live_... workspace key manages the budget itself. Managed services shows the setup. Managed LLM calls default to the Agent37 default model, a fast low-cost model we pick and keep current. You are not locked to it: the managed provider is OpenAI-compatible and lists its supported paid, tool-capable OpenRouter models at GET https://api.agent37.com/llm/v1/models. In Hermes, run /model and pick from the Agent37 provider’s list. In OpenClaw, run openclaw models list and set any agent37/... entry as the model. Whatever the model, billing stays the same: OpenRouter inference cost passed through with no Agent37 markup, metered against the budget and wallet.

How budgets work

A budget has two parts:

Monthly cap. A spending ceiling that resets at the start of each UTC month. It defaults to $0, so managed calls are refused until you grant headroom.
One-time credit. A ceiling that persists across months and is consumed only after the monthly portion is exhausted.

Budget figures are ceilings, not money. The workspace wallet is the only pot of dollars; raising a cap or topping up an instance moves no funds. The sum of caps across your instances can exceed the wallet balance, which is fine: caps bound each instance, the wallet bounds the total.

Set a budget at create

Pass budget in the create body to grant headroom from the first call.

integer

default:"0"

optional

Monthly managed-spend cap in micros. Resets each UTC month.

integer

default:"0"

optional

One-time headroom in micros. Persists until consumed.

curl -X POST https://api.agent37.com/v1/instances \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "research-bot",
    "budget": { "monthly_cap_micros": 5000000, "credit_micros": 1000000 }
  }'

import requests

H = {"Authorization": "Bearer sk_live_...", "Content-Type": "application/json"}
instance = requests.post(
    "https://api.agent37.com/v1/instances",
    headers=H,
    json={
        "name": "research-bot",
        "budget": {"monthly_cap_micros": 5000000, "credit_micros": 1000000},
    },
).json()

const H = {
  "Authorization": "Bearer sk_live_...",
  "Content-Type": "application/json",
};
const instance = await (await fetch("https://api.agent37.com/v1/instances", {
  method: "POST",
  headers: H,
  body: JSON.stringify({
    name: "research-bot",
    budget: { monthly_cap_micros: 5000000, credit_micros: 1000000 },
  }),
})).json();

Endpoints

Method	Path	Returns
`GET`	`/v1/instances/{id}/budget`	`200` the budget object
`PATCH`	`/v1/instances/{id}/budget`	`200` the updated budget object
`POST`	`/v1/instances/{id}/budget/top-up`	`200` the updated budget object
`GET`	`/v1/instances/{id}/usage`	`200` `{ period, total_micros, by_integration }`

All three budget endpoints return the same budget object.

The budget object

integer

The monthly spending ceiling.

integer

Managed spend counted against the cap this month.

integer

monthly_cap_micros minus monthly_consumed_micros, floored at 0.

string

The UTC month the counters cover, formatted YYYY-MM.

integer

One-time headroom left. Consumed only after the monthly portion is exhausted.

integer

Epoch seconds of the last budget write. The budget is first written when the instance is created; cap changes, top-ups, and managed spend all update it.

curl -X GET \
  https://api.agent37.com/v1/instances/ab12cd34ef/budget \
  -H "Authorization: Bearer sk_live_..."

import requests

response = requests.get(
    "https://api.agent37.com/v1/instances/ab12cd34ef/budget",
    headers={
        "Authorization": "Bearer sk_live_..."
    },
)
response.raise_for_status()
print(response.json())

const response = await fetch(
  "https://api.agent37.com/v1/instances/ab12cd34ef/budget",
  {
    method: "GET",
    headers: {
      "Authorization": "Bearer sk_live_..."
    },
  },
);
if (!response.ok) {
  throw new Error(await response.text());
}
console.log(await response.json());

{
  "monthly_cap_micros": 5000000,
  "monthly_consumed_micros": 412380,
  "monthly_remaining_micros": 4587620,
  "monthly_period": "2026-06",
  "credit_remaining_micros": 1000000,
  "updated_at": 1781136000
}

Set the monthly cap

PATCH /v1/instances/{id}/budget sets the cap for the current and future months. It takes effect immediately.

integer

required

The new monthly cap in micros. Must be a non-negative integer.

curl -X PATCH \
  https://api.agent37.com/v1/instances/ab12cd34ef/budget \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "monthly_cap_micros": 20000000
  }'

import requests

response = requests.patch(
    "https://api.agent37.com/v1/instances/ab12cd34ef/budget",
    headers={
        "Authorization": "Bearer sk_live_...",
        "Content-Type": "application/json"
    },
    json={
        "monthly_cap_micros": 20000000
    },
)
response.raise_for_status()
print(response.json())

const response = await fetch(
  "https://api.agent37.com/v1/instances/ab12cd34ef/budget",
  {
    method: "PATCH",
    headers: {
      "Authorization": "Bearer sk_live_...",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "monthly_cap_micros": 20000000
    }),
  },
);
if (!response.ok) {
  throw new Error(await response.text());
}
console.log(await response.json());

Setting the cap to 0 turns managed services off for the instance once any remaining top-up headroom is consumed.

Add one-time headroom

POST /v1/instances/{id}/budget/top-up adds to credit_remaining_micros. Use it for a burst of work you don’t want to bake into the monthly cap.

integer

required

Headroom to add, in micros. Must be a positive integer.

string

optional

Up to 64 characters matching ^[A-Za-z0-9_-]{1,64}$. Repeating a request with the same key returns the current budget without adding again, so retries are safe.

curl -X POST \
  https://api.agent37.com/v1/instances/ab12cd34ef/budget/top-up \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount_micros": 10000000,
    "idempotency_key": "monthly-burst-1"
  }'

import requests

response = requests.post(
    "https://api.agent37.com/v1/instances/ab12cd34ef/budget/top-up",
    headers={
        "Authorization": "Bearer sk_live_...",
        "Content-Type": "application/json"
    },
    json={
        "amount_micros": 10000000,
        "idempotency_key": "monthly-burst-1"
    },
)
response.raise_for_status()
print(response.json())

const response = await fetch(
  "https://api.agent37.com/v1/instances/ab12cd34ef/budget/top-up",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer sk_live_...",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "amount_micros": 10000000,
      "idempotency_key": "monthly-burst-1"
    }),
  },
);
if (!response.ok) {
  throw new Error(await response.text());
}
console.log(await response.json());

Read managed spend

GET /v1/instances/{id}/usage?month=YYYY-MM returns the instance’s managed-spend rollup for one UTC month. Omit month for the current month; an invalid value returns 400.

string

The UTC month covered, formatted YYYY-MM.

integer

Total managed spend for the month.

object

Per-service breakdown. llm carries cost_micros, calls, input_tokens, and output_tokens; brave, composio, and perflo carry cost_micros and calls. perflo is paid tools.

curl -X GET \
  https://api.agent37.com/v1/instances/ab12cd34ef/usage \
  --url-query "month=2026-06" \
  -H "Authorization: Bearer sk_live_..."

import requests

response = requests.get(
    "https://api.agent37.com/v1/instances/ab12cd34ef/usage",
    headers={
        "Authorization": "Bearer sk_live_..."
    },
    params={
        "month": "2026-06"
    },
)
response.raise_for_status()
print(response.json())

const query = new URLSearchParams({
  "month": "2026-06"
});

const response = await fetch(
  "https://api.agent37.com/v1/instances/ab12cd34ef/usage" + "?" + query,
  {
    method: "GET",
    headers: {
      "Authorization": "Bearer sk_live_..."
    },
  },
);
if (!response.ok) {
  throw new Error(await response.text());
}
console.log(await response.json());

{
  "period": "2026-06",
  "total_micros": 412380,
  "by_integration": {
    "llm": {
      "cost_micros": 391582,
      "calls": 42,
      "input_tokens": 184032,
      "output_tokens": 96110
    },
    "brave": { "cost_micros": 20000, "calls": 4 },
    "composio": { "cost_micros": 798, "calls": 7 },
    "perflo": { "cost_micros": 0, "calls": 0 }
  }
}

This endpoint covers managed spend on one instance. For everything the workspace spent, compute included, by day and by instance, use GET /v1/usage. See Billing.

When a managed call is refused

A managed call that can’t be covered fails with a 402 carrying one of two reasons. The instance keeps running either way; only managed calls are refused, and the refusal surfaces inside the instance on the call the agent was making, so the agent typically reports it in its reply.

Reason	What happened	Fix
`insufficient_balance`	The workspace wallet is empty.	Top up the wallet at agent37.com/dashboard/cloud/billing.
`instance_budget_exhausted`	The wallet has funds, but this instance hit its budget.	Raise the monthly cap with `PATCH .../budget`, or add headroom with `POST .../budget/top-up`.

For the Sandbox API error catalog, see Errors.

Connecting apps

The agent connects apps two ways. In conversation, ask it to connect Gmail, Slack, Notion, or any other Composio-supported app, and it replies with an authorization link your user opens to grant access. Or drive the flow over the Sandbox API; see App integrations.

Bring your own keys

To run a service on your own account, put your own provider key inside the instance with exec or the agent’s in-instance config. Calls made with your own keys go straight to the provider and never touch the managed meter or the budget.

Reference

Sandbox API

Agent API

Shared reference

Managed services & budgets

Rates

The managed model

How budgets work

Set a budget at create

Endpoints

The budget object

Set the monthly cap

Add one-time headroom

Read managed spend

When a managed call is refused

Connecting apps

Bring your own keys

​Rates

​The managed model

​How budgets work

​Set a budget at create

​Endpoints

​The budget object

​Set the monthly cap

​Add one-time headroom

​Read managed spend

​When a managed call is refused

​Connecting apps

​Bring your own keys

Rates

The managed model

How budgets work

Set a budget at create

Endpoints

The budget object

Set the monthly cap

Add one-time headroom

Read managed spend

When a managed call is refused

Connecting apps

Bring your own keys