Agentic Data Plane

Set Up Budgets

The Agentic Data Plane caps LLM spend with budgets and records every LLM call as a spending event. Set a budget to enforce a hard spending cap per agent, then read what you actually spend on the Cost and usage page and through breakdown queries by provider, model, user, agent, or provider type.

After completing these steps, you will be able to:

  • Set a per-agent budget that caps LLM spend and warns before the cap

  • Identify what spending data the Agentic Data Plane records automatically

  • View spend breakdowns by agent, model, and provider

Set a budget

A budget caps LLM spend over a recurring period. When an agent’s spend for the period reaches the budget’s hard limit, AI Gateway rejects that agent’s next LLM request with HTTP 429 until the period resets. A separate warning threshold fires before the cap, so you can react before AI Gateway cuts the agent off.

You manage per-agent budgets on the Budgets page. A budget identifies an agent by its resource name in the form agents/<slug>, the same identity that appears as agent_name in spend data.

A per-agent budget caps only calls that an agent makes, including calls it makes on a user’s behalf. The tenant default and overrides don’t cover a call that doesn’t come from an agent, such as a user calling AI Gateway directly. If AI Gateway can’t read current spend, it lets the request through.

A capped request gets HTTP 429 with an error body in the provider’s own rate-limit format, so client SDKs handle it like any other rate limit. The message names the budget, the spend against the cap, and when the period resets. For OpenAI-format providers, the error also carries the code budget_exceeded. Anthropic returns rate_limit_error, Google returns RESOURCE_EXHAUSTED, and Amazon Bedrock returns ThrottlingException.

How a budget works

Setting What it does

Limit

The hard cap on per-period spend. You set it in dollars in the UI; the API stores it in USD microcents (1 cent = 1,000,000 microcents). When a matching agent’s accrued spend for the period reaches this value, the agent’s next LLM request through the gateway gets HTTP 429. Spend resets to zero at the start of each period.

Warning threshold

A spend level, lower than the limit, at which Agentic Data Plane warns: gateway responses carry a SpendLimit-Warning header and Agentic Data Plane records a warning metric. Requests still pass. Must be greater than zero and less than the limit.

Period

How often the spend pool resets: daily, weekly, or monthly. Periods are calendar-aligned in UTC: daily at 00:00 UTC, weekly at 00:00 UTC Monday, monthly at 00:00 UTC on the first of the month.

Target agent

Which agent the budget applies to. Leave it unset to create the tenant default budget. Set it to an agent’s resource name (agents/<slug>) to create a per-agent override.

Default and per-agent override budgets

You can have one default budget per tenant and at most one override per agent:

  • The default budget (no target agent) gives every agent its own independent pool of the limit per period. One agent reaching its cap doesn’t affect another.

  • A per-agent override targets a single agent by resource name (agents/<slug>) and replaces the default for that agent. Use an override to give a specific agent a higher or lower cap than the fleet default. Adding an override partway through a period doesn’t reset the agent’s usage: while a default budget exists, a new override inherits the default’s current spending window instead of starting a fresh one, so spend the agent already accrued this period still counts toward the override’s cap. Deleting and recreating an override behaves the same way, so an agent can’t gain fresh runway by having its override recreated mid-period. Editing a budget’s limit never moves the window either; spend already accrued this period keeps counting. (If no default budget exists, the override starts a new window when you create it.)

The target agent is immutable. To move an override to a different agent, delete it and create a new one. An override matches on the agent’s resource name, so recreating an agent with the same name keeps the override pointed at it; the new instance counts as a continuation for budget purposes. When you read a budget, it also reports the current period’s spend, when the period started, when it resets, and (for the default budget) the agent currently closest to its cap.

Set a budget in the UI

Open Budgets in the sidebar. The page leads with a Needs attention section, then a card for the default budget, then a table of the agents that have a budget of their own. One Create budget button covers both the default budget and an agent’s own budget.

The default budget card shows the per-agent limit and its period, the Warn at amount, and how many agents on the default are within budget, near the limit, or over the limit.

Needs attention stays collapsed and carries the number of budgets that need it. Expand it to see each one, worst first, with its share of its limit spent so far. A budget over its limit is labeled Blocking, and one that has passed its warning threshold is labeled Warning. The default budget appears as a single row that counts the agents in trouble, such as 3 agents over limit. Select a row to open that budget.

An agent counts as near the limit after its spend for the period reaches the budget’s own Warn at amount, so moving the warning threshold also moves where the near-limit status starts. Every surface that flags a budget reads it the same way.

The agent budgets table shows each agent’s Agent name, its Spend this period against the cap, its Tags, and its Warn at amount. The table is sorted by agent name. Sort it by Spend this period instead to bring the agents closest to their limit to the top. Search the table by agent or budget name, or filter it by Status (Over budget, Past warn threshold, or Under warn threshold). A narrow window hides Tags first, then Warn at, then Spend this period. Select a row to open that agent’s budget.

To create a budget:

  1. Click Create budget.

  2. Under Scope, select the agent this budget covers. Leave Agent empty (All agents) to create the default budget instead. An agent that already has its own budget can’t be selected, and you can’t create a second default budget. The form says which budget it’s about to create.

  3. Under Limit, enter a dollar amount and select Day, Week, or Month. Set Warning threshold as a percentage of the limit, from 1 to 99 (80 by default). The form shows the dollar amount that percentage works out to, and when the period resets in UTC.

  4. Check the Preview section, which names the budget resource and states the limit and period in a sentence. For a default budget, it also counts the agents that keep their own budget.

  5. Optionally, expand Advanced to set a Display name and to add Tags, key/value pairs that organize and filter budgets and that access policies can read in their conditions. Enter a tag key and a tag value, then press Enter or click the add (+) button. For the limits and rules that apply to tags on every resource, see Tag Resources.

  6. Click Create budget.

Agentic Data Plane names an agent’s budget after the agent, then highlights the new budget on the Budgets page.

Open the default budget from the Budgets page to see its own page. It shows the limit, which applies to each agent separately rather than as one shared pool, when the period next resets, the Warn at amount, and how many agents are on the default and how many of them are within budget, near the limit, or over the limit. A What each agent has spent table lists each agent’s spend so far toward its limit.

To change the default budget, open it from the Budgets page and edit it in place. To change an agent’s budget, select its row and click Edit. A budget’s tags appear on its page, and the agent budgets table has a Tags column that a narrow window hides first. A budget’s own tags don’t affect which agents it covers. The target agent decides that.

Read the spend projection

An agent’s budget page carries a Spend projection card that estimates where the agent’s spend lands when the budget period resets. The card reports Recorded this period and Projected at reset, and charts recorded spend as a solid line, the projection as a dashed line through the reset, and the limit as a dotted line. Use it to see whether an agent is on course to hit its cap before the period ends.

The projection extrapolates from the complete hours or days of the current period, and the card names how many it used. It assumes usage and pricing don’t change, and it doesn’t account for the gateway blocking requests at the cap, so treat it as an estimate rather than a forecast you can rely on. A period with fewer than two complete spending buckets has no projection, and the card says so. The default budget has no projection card.

Manage budgets through the API

BudgetService exposes standard create, read, update, and delete operations:

Method Use it to

CreateBudget

Create the tenant default or a per-agent override.

GetBudget, ListBudgets

Read one budget, or list all budgets, each with current-period spend status. You can filter ListBudgets by name and by the agent a per-agent override targets.

UpdateBudget

Change the limit, warning threshold, or period. Send a field mask naming the fields you change.

DeleteBudget

Remove a budget. Deleting the default removes the per-agent pools; deleting an override falls that agent back to the default.

When you call CreateBudget, set the pooling mode to per-agent (POOLING_MODE_PER_AGENT) for both the tenant default and a per-agent override. A budget name starts with a lowercase letter and contains only lowercase letters, digits, and hyphens.

A service account needs the matching dataplane_adp_budget_* permission for each operation (create, get, list, update, or delete). See Budget permissions.

You can manage the same budgets with the rpk ai budget commands. Enter amounts in dollars with --limit-usd and --warn-at-usd, as a positive decimal with at most eight decimal places, instead of converting to microcents yourself. Each one stands in for the matching microcent flag rather than joining it, so pass only one of a pair. To check a change before it reaches the server, add --dry-run, which prints the request and exits.

What Agentic Data Plane records automatically

Every LLM call routed through AI Gateway becomes a spending event. Each event captures:

  • Input tokens, output tokens, and cached tokens.

  • Total cost (in microcents).

  • Request count.

  • The provider, model, user, and organization context the call ran under.

No setup required: the gateway captures spending the moment your first agent runs through it.

Agentic Data Plane tracks streaming and non-streaming requests the same way, and attributes cache-write tokens (Anthropic 4.x, OpenAI 4.x prompt caches) correctly on streaming responses, so cost rollups stay accurate when an agent reuses long system prompts.

Agentic Data Plane reports cost in microcents. 1 cent = 1,000,000 microcents, so $1 = 100,000,000 microcents. Divide the total cost in microcents by 100,000,000 to convert to dollars.

Per-request pricing variations

A few request- or response-time signals change the rate Agentic Data Plane applies to a single call. You don’t configure these; the spending pipeline picks them up from the upstream response or request and bills accordingly.

  • Anthropic fast mode: Anthropic exposes a fast-mode option on some models (for example, Opus 4.6 fast) that carries a per-token premium over the default rate. Agentic Data Plane reads the speed field on each Anthropic response and bills fast-mode calls at the model’s fast-mode rate. Requests without a speed field fall back to the default rate.

  • Context-tier pricing: A few models charge a different rate after a request crosses a context-length threshold. Gemini Pro, for example, prices requests above a 128K-token context at a higher tier than shorter requests. Agentic Data Plane uses the call’s context-token count so requests at or above the threshold bill at the tiered rate automatically.

  • OpenAI service tier: OpenAI reports the service tier it actually served a request at, which isn’t always the tier the request asked for. Agentic Data Plane reads the reported tier and bills the call at that tier’s rate instead of the standard rate, so a lower-cost tier keeps its discount and a faster tier its premium. The tier is recorded on the spending event as service_tier, with values such as default, flex, priority, and ultrafast. A request OpenAI reports as fast is recorded as priority. A response that reports no tier, or a tier the model has no rate card for, bills at the standard rate. Requests to OpenAI-compatible endpoints, including Amazon Bedrock traffic on the Responses API, are read the same way.

Where to view your spend

The Budgets page shows each budget’s usage against its cap. For spend analysis, use these surfaces:

Surface Use it for

Cost and usage page (in the sidebar)

Spend, requests, and tokens for a time window against the period before it; a breakdown of spend by agent, model, provider, user, or tag; and a chart of any one of them against the gateway total, with CSV export. See Analyze Cost and Usage.

Breakdown queries

Aggregated spend by provider, model, user, agent, or provider type, available through GetSpendingBreakdown for programmatic access.

Agents list

Comparing agents' 30-day spend and budget usage side by side. See Read the columns.

Every breakdown and time-series query reads from the same SpendingFilter shape: a time range plus optional provider_name, model_id, user_email, agent_name, agent_uid, or organization_id filters. Combine filters to scope a query (for example, "all spend on Anthropic for user alice in April"). You can break results down by provider, model, user, agent, or provider type; organization_id is a filter only, not a breakdown dimension.

For more expressive queries, SpendingFilter also accepts an AIP-160 filter expression that lets you combine and negate dimensions in a single string (for example, provider_name="anthropic" AND model_id!="claude-sonnet-4-6"). The convenience fields and the filter expression compose; populate one or both.

user_email and organization_id are populated automatically from the request’s authenticated identity (the caller’s email and organization), so spend is attributed without any setup on your part.

Query spend programmatically

SpendingService.GetSpendingBreakdown is the canonical RPC for pulling spend out of Agentic Data Plane. Use it for chargeback reporting, scheduled emails, internal cost dashboards, or any workflow the built-in UI doesn’t cover.

Authenticate

SpendingService uses the same OIDC client-credentials grant as the rest of AI Gateway. Mint a service-account access token using the flow in Authenticate with OIDC client credentials, then pass the token in the Authorization: Bearer <token> header on every call. The service account needs dataplane_adp_spending_get, which grants read access to all spend in the tenant. See Spending permissions.

Request shape

GetSpendingBreakdown takes a SpendingFilter plus a dimension. The filter accepts:

Field Meaning

start_time, end_time

RFC 3339 timestamps bracketing the window. Required.

provider_name

Restrict to one LLM provider (matches the Name field on the provider’s detail page).

model_id

Restrict to one model identifier (claude-sonnet-4-6, gpt-5.2, and so on). The value resolves to the model’s whole family, so its aliases and its dated versions all match: gpt-4o covers gpt-4o-2024-08-06, and gpt-4o-2024-08-06 returns the same total. A name that differs by more than a trailing date stays separate, so gpt-4o-mini is its own model, as is each regional version of a model served through Amazon Bedrock. A model identifier that no provider catalog lists matches exactly.

user_email

Restrict to one identified user, matched on the caller’s email. Anonymous traffic is excluded.

agent_name

Restrict to one agent by its resource name (agents/<slug>), recorded on every call made by or on behalf of an agent. Leave it empty to match every row, including direct user calls; set it to scope spend to a single agent, summed across every instance that has used the name.

agent_uid

Restrict to one agent instance, identified by the immutable UUID minted at agent creation. Valid on its own; combine it with agent_name only as a label convenience (the two conditions are ANDed). Use it to exclude spend from a previously deleted agent that reused the same name.

organization_id

Restrict to one organization. Multi-tenant deployments only.

filter

AIP-160 expression that combines and negates dimensions in a single string (for example, provider_name="anthropic" AND model_id!="claude-sonnet-4-6"). Composes with the structured fields in this table; populate one or both. An equality or inequality test on model_id resolves the model family the same way the model_id field does, so the inequality in that example excludes every dated version of the model. Ordering and substring comparisons test the stored identifier instead.

The dimension value chooses the breakdown dimension. Valid values are the BreakdownDimension enum: BREAKDOWN_DIMENSION_PROVIDER, BREAKDOWN_DIMENSION_MODEL, BREAKDOWN_DIMENSION_USER, BREAKDOWN_DIMENSION_AGENT, BREAKDOWN_DIMENSION_PROVIDER_TYPE, BREAKDOWN_DIMENSION_TAG, and BREAKDOWN_DIMENSION_AGENT_UID.

A breakdown on BREAKDOWN_DIMENSION_AGENT keys on the agent’s resource name (agents/<slug>) and excludes rows with no agent (direct user calls), the same way the other dimensions skip empty keys. Spend is summed across every instance that has used the name, so an agent that was deleted and recreated appears as a single entry. For history reads, use BREAKDOWN_DIMENSION_AGENT_UID: the name-keyed breakdown silently merges unrelated agents that reused the same name, so BREAKDOWN_DIMENSION_AGENT is deprecated for that use (it is still accepted, and its behavior is unchanged).

BREAKDOWN_DIMENSION_AGENT_UID keys on the agent’s immutable UUID instead, so each incarnation of a reused name appears as its own entry, with the agent’s name returned alongside as a label. Rows with no agent are excluded.

BREAKDOWN_DIMENSION_TAG groups spend by the value of a tag you set on your agents (for example, department) and takes an extra tag_key field. Spend rows without the tag collapse into a single empty-string key. Use it to attribute cost to a department, team, or environment. See Track Spend by Tag.

To discover which cost-allocation tag keys exist before breaking down by one, call GetSpendingTagKeys with a start and end time. It returns the distinct tag keys observed on spend within that window, sorted ascending, and returns an empty list when no tagged spend exists in the range.

cURL example

Pull per-user spend for the last 7 days against an Anthropic provider:

ACCESS_TOKEN="<oidc-access-token>"   # from the client_credentials flow
DATAPLANE_BASE="https://aigw.<cluster-id>.clusters.rdpa.co"

curl -s --request POST \
  --url "${DATAPLANE_BASE}/redpanda.api.adp.v1alpha1.SpendingService/GetSpendingBreakdown" \
  --header "Authorization: Bearer ${ACCESS_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data '{
    "filter": {
      "start_time": "2026-05-17T00:00:00Z",
      "end_time":   "2026-05-24T00:00:00Z",
      "provider_name": "prod-anthropic"
    },
    "dimension": "BREAKDOWN_DIMENSION_USER"
  }' | jq

The response carries one entries row per user in the window. Each entry has a key (the user) and a stats object with totalCostMicrocents, totalRequests, totalTokens, and per-bucket input, output, and cached usage. Fields whose value is zero are left out of the response. Divide totalCostMicrocents by 100,000,000 to convert to dollars.

Python example

Generated client code lives in the proto bundle. If your project doesn’t already import those generated clients, drive SpendingService over plain HTTPS:

import os, requests
from datetime import datetime, timedelta, timezone

token = os.environ["ACCESS_TOKEN"]            # from the client_credentials flow
base  = os.environ["DATAPLANE_BASE"]          # https://aigw.<cluster-id>.clusters.rdpa.co
end   = datetime.now(timezone.utc)
start = end - timedelta(days=7)

body = {
    "filter": {
        "start_time": start.isoformat().replace("+00:00", "Z"),
        "end_time":   end.isoformat().replace("+00:00", "Z"),
        "filter": 'provider_name="prod-anthropic"',
    },
    "dimension": "BREAKDOWN_DIMENSION_USER",
}

r = requests.post(
    f"{base}/redpanda.api.adp.v1alpha1.SpendingService/GetSpendingBreakdown",
    headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"},
    json=body,
)
r.raise_for_status()
for entry in r.json().get("entries", []):
    stats = entry["stats"]
    dollars = int(stats.get("totalCostMicrocents", 0)) / 100_000_000
    print(f"{entry['key']}: ${dollars:,.2f}  ({stats.get('totalRequests', 0)} requests)")

The proto-generated client (Connect-Go or grpc-python) is the long-term recommendation; the cURL and requests examples are for quick scripting.

SpendingService exposes additional methods that follow the same SpendingFilter shape:

  • GetSpendingSummary: Total spend, tokens, and requests for the range, with no breakdown. Also returns the previous comparable period so you can show a trend.

  • GetSpendingTimeSeries: Spend bucketed over the time range (hourly or daily), for chart-style consumers.

  • GetSpendingTimeSeriesByDimension: Time-series buckets split by a breakdown dimension (top-N keys by cost), for stacked charts. Reports truncated_key_count when more keys matched than were returned.

Guardrail cost

Guardrail evaluation is not counted against budgets and does not appear in Agentic Data Plane cost reporting. When a guardrail delegates a policy to Amazon Bedrock, AWS bills that evaluation directly to the AWS account whose credentials the guardrail uses. For current rates, see Amazon Bedrock pricing.

For what each policy does, see How guardrails work and Guardrail policy reference.

Override per-model pricing

The Agentic Data Plane ships with default per-model pricing per provider, covering input, output, and cache-read prices for every model in the built-in catalog. Cost reporting uses these prices when it computes per-call spend, which is why every dollar value on the Cost and usage page and in SpendingService queries works without any setup.

If your organization negotiates non-standard pricing, or you want to track spend against an internal chargeback rate, override the rates as part of configuring an LLM provider. Overrides are scoped to a single provider, where you edit the rate per model. See Override per-model pricing.

Check your understanding

Answer each question, then expand it to compare.

The default budget is $100 per month and two agents are running. Do they share the $100?

No. The default budget gives every agent its own independent pool of the limit per period. One agent reaching its cap doesn’t affect another.

An agent reaches its cap partway through the month. What does its next LLM request get, and when does the agent recover?

The gateway rejects the request with HTTP 429. Requests pass again when the period resets, which for a monthly budget is 00:00 UTC on the first of the month.

On the 20th of the month you add a per-agent override to an agent that has already spent $60 under the default budget. Does its usage reset?

No. While a default budget exists, a new override inherits the default’s current spending window, so the $60 already accrued counts toward the override’s cap. Deleting and recreating the override behaves the same way.

An agent’s spend crosses its warning threshold. Does anything stop?

No. Requests still pass. Gateway responses carry a SpendLimit-Warning header and Agentic Data Plane records a warning metric. Only reaching the hard limit blocks the agent’s next LLM request.

Do guardrail evaluations count against an agent’s budget?

No. Guardrail evaluation isn’t counted against budgets and doesn’t appear in Agentic Data Plane cost reporting. When a guardrail delegates a policy to Amazon Bedrock, AWS bills that evaluation to the AWS account whose credentials the guardrail uses.

Next steps