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.

Redpanda Agentic Data Plane enforces budgets per agent. 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.

Budgets cap only calls made as an agent, including calls an agent makes on a user’s behalf. Calls that don’t run as an agent, such as a user calling AI Gateway directly, are never capped. 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 AWS 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 shows the tenant default budget as a card: its cap and period, the warn threshold, and how many agents are within budget, near the limit, or over the limit. Per-agent overrides appear in a table below the card, with each override’s Agent override target, Period, current Usage against the cap, Warn at threshold, and when it was last Updated.

Click the Period, Usage, or Updated column header to reorder the overrides. Sorting by Usage ranks them by how much of the cap each has spent, which brings the agents closest to their limit to the top.

To create the tenant default budget:

  1. Click Create default budget.

  2. Under Budget, set Limit spend to to a dollar amount and choose a period (day, week, or month). Use the quick-set chips ($25, $100, $500, $1,000) for common values.

  3. Under Alerts, drag the Warn at slider to set the warning threshold as a percentage of the cap (80% by default).

  4. Review the Preview section, which summarizes the budget, period, and the warn and block thresholds in dollars, then click Create default budget.

Open the default budget from the Budgets page to see its detail view: the per-agent spending limit (each agent gets its own limit, not one shared pool), the reset schedule, the warn threshold, and how much each agent has spent so far toward its limit.

To give one agent a different cap, click Add override, pick the agent (each agent can have at most one override; agents that already have one are grayed out), then set the Budget and Warn at controls the same way. Agentic Data Plane derives the override’s name from the agent. You can change its Display name later by editing the override.

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.

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), the only mode supported. 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.

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.

Where to view your spend

The Budgets page shows each budget’s usage against its cap. For spend analysis, use the Cost and usage page and breakdown queries:

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.

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).

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 above; populate one or both.

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 AWS Bedrock, AWS bills that evaluation directly to the AWS account whose credentials the guardrail uses. For current rates, see AWS 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 AWS Bedrock, AWS bills that evaluation to the AWS account whose credentials the guardrail uses.

Next steps