API Headers and Overflow Management

Decide which requests consume your capacity

Reserving capacity solves only half the problem: you still need to choose which requests actually benefit from it. Provisioned throughput isn’t a blanket purchase you make once at the start of the month; it’s a mechanism you control call by call. xAI exposes dedicated HTTP headers for this purpose that arbitrate, request by request, between your dedicated capacity and the shared pool. A fixed allocation thus becomes an operational lever your teams manipulate directly from application code.

Voluntarily bypass dedicated capacity

The first header serves to exclude a request from your allocation:

curl https://api.x.ai/v1/chat/completions \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "x-pt-disable: true" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.3",
    "messages": [{"role": "user", "content": "Summarize this document."}]
  }'

Giving up your own capacity seems counterintuitive. Four situations justify it in daily operations. First, non-critical tasks: a batch analysis launched at 10 PM or a deferred processing job doesn’t need a latency guarantee, and it would be a shame for it to consume the allocation paid for interactive traffic. Second, preserving capacity during peaks: by disabling provisioned throughput on secondary processing, you free up allocation exactly when priority requests arrive in high volume. The header also serves for A/B testing, when you want to measure the actual performance gap between dedicated and shared capacity on your own load rather than on a vendor promise. Finally, it is valuable for debugging: forcing the request through the shared pool tells you immediately whether the observed anomaly comes from the provisioned capacity or your code.

Route a request to a specific pool

The second header directs the call to an identified capacity pool:

curl https://api.x.ai/v1/chat/completions \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "x-pt-id: pool-support-client" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.3",
    "messages": [{"role": "user", "content": "How can I help you?"}]
  }'

This header becomes indispensable as soon as multiple applications within your organization call Grok. You then create separate pools—a pool-support for the customer support chatbot, a pool-analysis for document analysis, a pool-internal for business tools—and each operates independently. Segmentation isolates performance: the document analysis campaign launched on a Monday morning no longer degrades support response times. It also produces consumption broken down by usage, thus a factual basis for chargebacks or arbitration, where previously you relied on guesswork. And it inherently prevents a single application from monopolizing capacity to the detriment of others.

What happens in case of overflow

When traffic exceeds provisioned capacity, the fallback is automatic and silent: the request goes to the shared pool on pay-as-you-go, standard model rates apply, and it is subject to usual rate limits. No error is returned; your application sees nothing happen.

This discretion has two sides. On the availability side, the news is good: you will never encounter a 429 error caused by exceeding provisioned capacity. On the finance and service quality side, it is less good. The request is billed at the pay-as-you-go rate, potentially higher; response times may vary since processing takes place on shared infrastructure; and above all the 99.9% SLA covers only requests processed within provisioned throughput. An overflow therefore breaks nothing, it simply makes you slip quietly out of the scope you pay for. The Management API exposes the proportion of requests processed in provisioned mode versus pay-as-you-go: examine this ratio each month just like a bill. A rising overflow rate is the signal that you need to increase the allocation.

Translate priority into application code

Rather than multiplying call functions, the most solid practice consists of qualifying priority at the moment the request is issued:

import httpx

def query_grok(prompt: str, priority: str = "normal"):
    headers = {
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    }

    if priority == "low":
        headers["x-pt-disable"] = "true"
    elif priority == "high":
        headers["x-pt-id"] = "pool-critical"

    response = httpx.post(
        "https://api.x.ai/v1/chat/completions",
        headers=headers,
        json={
            "model": "grok-4.3",
            "messages": [{"role": "user", "content": prompt}],
        },
    )
    return response.json()

The priority parameter becomes the only decision exposed to business logic, and the routing policy remains concentrated in a single function that you evolve without touching the rest. Review your own calling code and sort each entry point into one of three categories: the exercise regularly shows that a solid half of traffic had no need for dedicated capacity.

Key takeaways

• The x-pt-disable: true header bypasses provisioned capacity for a request
• The x-pt-id header routes to a specific capacity pool
• Overflows automatically fall back to pay-as-you-go without error
• Segmentation into pools allows isolating performance and tracking consumption by application
• Monitor the overflow rate to adjust your allocation if necessary