docs: query cost limits for API tokens and roles

content/docs/(documentation)/console/intelligence/ai-agents-overview.mdx

@@ -62,8 +62,11 @@ You don't need to follow the guidance below for remote Axiom MCP Server. It uses
     - Avoid ingest permissions unless explicitly required. If the agent needs to ingest data, scope the token to the specific datasets.
     - Never grant delete, admin, or organization-level permissions.
 - Set a short expiry for the token (hours or days rather than months).
+- Set [query cost limits](/console/intelligence/query-cost-limits) on the token. A capped token bounds your worst-case query costs in advance, no matter how many queries the agent runs.
 - Rotate tokens regularly as part of your security practices.
 
+Query cost limits also cover the remote Axiom MCP Server: its OAuth sessions act as your user account, so limits on your roles cap what agents can spend on your behalf. For more information, see [Set query cost limits for AI agents](/console/intelligence/query-cost-limits).
+
 ## Get started
 
 <CardGroup cols={2}>

content/docs/(documentation)/console/intelligence/mcp-server.mdx

@@ -307,6 +307,15 @@ The remote MCP Server uses OAuth for authentication which handles credential iso
 
 For the local setup or when using [Axiom Skills](/console/intelligence/skills), you configure API tokens directly. For detailed guidance on secure token configuration, see [Token hygiene for AI agents](/console/intelligence/ai-agents-overview#token-hygiene-for-ai-agents).
 
+## Limit query costs
+
+Query cost limits let you cap the hourly and daily query costs of an AI agent so it can query your data autonomously without creating unexpected costs:
+
+- For the local setup, set query cost limits on the API token you create for the agent.
+- For the remote MCP Server, the agent acts as your user account through OAuth, so set query cost limits on your roles instead.
+
+For more information, see [Set query cost limits for AI agents](/console/intelligence/query-cost-limits).
+
 ## Use MCP Server
 
 After setting up the Axiom MCP Server, you can:

content/docs/(documentation)/console/intelligence/query-cost-limits.mdx

@@ -0,0 +1,72 @@
+---
+title: Set query cost limits for AI agents
+description: 'This page explains how to cap hourly and daily query costs on API tokens and roles so that AI agents can query your data autonomously without creating unexpected costs.'
+sidebarTitle: Query cost limits
+keywords: ["ai agents", "query cost limits", "budget", "mcp", "api tokens", "roles", "query usage", "429"]
+---
+
+AI agents are heavy query users. An agent investigating an incident or exploring a dataset can run hundreds of queries in minutes, and unlike a human, it doesn’t pause to consider what the session costs. Query cost limits put a hard cap on that risk: you give a token or a role an hourly and a daily query budget in dollars, and Axiom blocks further queries for that identity when the budget is spent. The block lifts automatically when the window resets.
+
+With a capped token, you can let an agent work autonomously against your data and know your worst case in advance: an agent with a $1 hourly and $10 daily limit can never spend more than $10 per day on queries, no matter what it does.
+
+<Note>
+Query cost limits are available on the Axiom Cloud and Enterprise plans.
+
+Query cost limits are separate from your organization’s [monthly spending limit](/reference/usage-billing#spending-limit). The spending limit caps your whole organization’s bill; query cost limits cap the query costs of individual tokens and members.
+</Note>
+
+## How query cost limits work
+
+- Limits apply to **query costs**: the billed cost of the query compute (GB-hours) an identity uses, measured the same way as in [Usage and billing](/reference/usage-billing). Ingest, storage, and other operations don’t count towards the limit and are never blocked by it.
+- You can set an **hourly limit**, a **daily limit**, or both, in dollars. The hourly window resets at the top of each hour (UTC), and the daily window resets at midnight UTC.
+- When an identity exceeds a limit, its query requests fail with HTTP status code `429` until the window resets. Other requests continue to work as normal.
+
+You can set query cost limits on two kinds of identity:
+
+- **API tokens.** The limit caps everything that authenticates with that token. Use token limits for agents that hold an API token: local MCP server setups, [Axiom Skills](/console/intelligence/skills), coding agents like Claude Code, and any script or SDK.
+- **Roles.** The limit caps each member that holds the role, individually. A member’s queries count against their budget whether they query in the Axiom console, with a personal access token, or through an OAuth session such as the remote [Axiom MCP Server](/console/intelligence/mcp-server), because all of these act as the member. If a member holds several roles with limits, the strictest limit for each window applies.
+
+## Give an agent a budget
+
+The typical setup for an agent that connects with an API token:
+
+1. Click <Icon icon="gear" iconType="solid"/> **Settings > API tokens**, and then click **New API token**.
+1. Create a dedicated token for the agent with the minimum permissions it needs. For more information, see [Token hygiene for AI agents](/console/intelligence/ai-agents-overview#token-hygiene-for-ai-agents).
+1. In **Query cost limits**, enter an hourly limit, a daily limit, or both, in dollars.
+1. Click **Create**, and then configure your agent with the new token.
+
+The agent now queries freely within its budget. If it exhausts the budget, its queries fail with an error that states the limit and when it resets.
+
+To add limits to an existing token, click <Icon icon="gear" iconType="solid"/> **Settings > API tokens**, select the token, and then edit **Query cost limits**. The token page also shows live usage meters for each limit with a countdown to the next reset.
+
+If your agents connect through the remote Axiom MCP Server, they authenticate with OAuth and act as your user account, so token limits don’t apply to them. Instead, set limits on a role you hold. Role limits cap everything you run as that member, including your own console queries.
+
+## Set limits on a role
+
+To cap the query costs of each member that holds a role:
+
+1. Click <Icon icon="gear" iconType="solid"/> **Settings > Roles**, and then select the role.
+1. In **Query cost limits**, click **Edit**.
+1. Enter an hourly limit, a daily limit, or both, in dollars, and then save.
+
+The limit applies to each member individually, not to the role as a group. For example, a $5 daily limit on a role with 10 members lets each member spend up to $5 per day.
+
+Role limits work on both built-in and custom roles.
+
+## Monitor usage against limits
+
+- To see how much of its budget a token has used, click <Icon icon="gear" iconType="solid"/> **Settings > API tokens**, and then select the token. The usage meters show current usage against each limit and when the window resets.
+- To see usage across members, click <Icon icon="gear" iconType="solid"/> **Settings > Users**. Members with limits show their current query usage.
+- To see your own usage, go to your profile. The **Query usage** section shows your effective limits and current usage.
+
+Axiom only tracks and displays usage for identities that have limits configured.
+
+## What happens when a limit is reached
+
+When a token or member exceeds a limit, query requests return HTTP status code `429` with a `Retry-After` header that states the number of seconds until the window resets. The error message identifies which limit tripped, for example the token’s hourly limit or the member’s daily limit.
+
+- Queries from that identity are blocked until the window resets. No action is needed: an hourly limit unblocks at the top of the next hour (UTC), a daily limit at midnight UTC.
+- Other identities are unaffected. Other tokens, members, monitors, and dashboards keep querying as usual.
+- Ingest and management operations from the limited identity keep working.
+
+To unblock an identity before the window resets, raise or clear its limits. The change takes effect for new queries within moments.

content/docs/(documentation)/reference/optimize-usage.mdx

@@ -49,6 +49,10 @@ In calculating query costs, Axiom considers any request that queries your data a
 
 Each query is charged at the same rate, irrespective of its origin.
 
+### Cap query costs per token or role
+
+To put a hard cap on the query costs of an API token or a member, set hourly and daily query cost limits on API tokens and roles. This is particularly useful for AI agents and other automated query workloads. For more information, see [Set query cost limits for AI agents](/console/intelligence/query-cost-limits).
+
 Each monitor run counts towards your query costs. For this reason, the frequency (how often the monitor runs) can have a slight effect on query costs.
 
 ### Run queries and understand costs

content/docs/(documentation)/reference/tokens.mdx

@@ -57,6 +57,14 @@ After creating an API token, you can’t change the privileges assigned to that
 1. Click **Create**.
 1. Copy the API token that appears and store it securely. It won’t be displayed again.
 
+### Limit query costs of an API token
+
+On the Axiom Cloud and Enterprise plans, you can cap the hourly and daily query costs of an API token, in dollars. When the token exceeds a limit, its query requests fail with HTTP status code `429` until the window resets. Ingest and other operations are unaffected. This is particularly useful for tokens you give to AI agents.
+
+To set limits when you create a token, enter an hourly limit, a daily limit, or both in **Query cost limits**. To add or change limits on an existing token, click <Icon icon="gear" iconType="solid"/> **Settings > API tokens**, select the token, and then edit **Query cost limits**. The token page shows the token’s current usage against each limit.
+
+For more information, see [Set query cost limits for AI agents](/console/intelligence/query-cost-limits).
+
 ### Regenerate API token
 
 Similarly to passwords, it’s recommended to change API tokens regularly and to set an expiration date after which the token becomes invalid. When a token expires, you can regenerate it.

content/docs/(documentation)/reference/usage-billing.mdx

@@ -51,6 +51,8 @@ For example, if you have used up the query compute allowance included in your pr
 
 Even if you reach your spending limit, you can still initiate purchases manually such as buying add-ons and credits.
 
+The spending limit applies to your whole organization. To cap the query costs of individual API tokens or members instead, for example for AI agents, set [query cost limits](/console/intelligence/query-cost-limits) on API tokens and roles.
+
 To set a monthly spending limit:
 
 1. Ensure you have permissions to modify billing. For more information, see [Role-Based Access Control](/reference/settings).

docs.json

@@ -196,6 +196,7 @@
                 "pages": [
                   "console/intelligence/ai-agents-overview",
                   "console/intelligence/mcp-server",
+                  "console/intelligence/query-cost-limits",
                   "console/intelligence/agent-created-orgs",
                   {
                     "group": "Skills",