Managed services & budgets

Every instance is created with managed credentials for three services: LLM calls, web search (Brave), and app integrations (Composio). The agent uses them out of the box. Managed calls route and meter through Agent37, so there are no provider or integration keys for you to manage. Each 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	Provider cost, passed through with no markup
Web search (Brave)	$0.005 per call (5,000 micros)
Composio	$0.000114 per call (114 micros)

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

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 every available paid model at its /v1/models endpoint, so the agent can switch from inside the session. 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: provider cost passed through with no 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"

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

integer

default:"0"

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 https://api.agent37.com/v1/instances/ab12cd34ef/budget \
  -H "Authorization: Bearer sk_live_..."

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

budget = requests.patch(
    "https://api.agent37.com/v1/instances/ab12cd34ef/budget",
    headers=H,
    json={"monthly_cap_micros": 20000000},
).json()

const budget = await (await fetch(
  "https://api.agent37.com/v1/instances/ab12cd34ef/budget",
  {
    method: "PATCH",
    headers: H,
    body: JSON.stringify({ monthly_cap_micros: 20000000 }),
  },
)).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

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": "june-burst-1" }'

budget = requests.post(
    "https://api.agent37.com/v1/instances/ab12cd34ef/budget/top-up",
    headers=H,
    json={"amount_micros": 10000000, "idempotency_key": "june-burst-1"},
).json()

const budget = await (await fetch(
  "https://api.agent37.com/v1/instances/ab12cd34ef/budget/top-up",
  {
    method: "POST",
    headers: H,
    body: JSON.stringify({
      amount_micros: 10000000,
      idempotency_key: "june-burst-1",
    }),
  },
)).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 and composio carry cost_micros and calls.

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

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

Usage covers managed spend only. Compute charges never appear here; the full billing ledger lives in the dashboard, not on /v1. 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 hosting 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 Hosting 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.

Get started

Build with Agent37

Hosting API

Agent API

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