Reserving Priority Capacity for User Traffic with service_tier

Setting service_tier on a request

Specifying it is simple — add one line to the Messages API request body. Here is the Python example.

import anthropic
 
client = anthropic.Anthropic()
 
# Background job: do not consume the priority pool
message = client.messages.create(
    model="claude-haiku-4-5-20251001",
    max_tokens=1024,
    service_tier="standard_only",  # keep priority capacity free
    messages=[{"role": "user", "content": "Summarize this article in 3 sentences"}],
)
 
# The tier that actually served the request shows up in usage
print(message.usage.service_tier)  # e.g. "standard"

The same idea applies in TypeScript with the official SDK.

import Anthropic from "@anthropic-ai/sdk";
 
const client = new Anthropic();
 
const message = await client.messages.create({
  model: "claude-haiku-4-5-20251001",
  max_tokens: 1024,
  service_tier: "standard_only", // pin background jobs to standard
  messages: [{ role: "user", content: "Summarize this article in 3 sentences" }],
});
 
console.log(message.usage.service_tier); // "standard"

For the user-facing synchronous path, either leave it unset (which means auto) or write service_tier: "auto" explicitly. Being explicit makes the intent obvious when you reread the code: this path is allowed to use the priority pool.

Confirm the reality with usage.service_tier

What actually moved the needle first was observation, not configuration. Whether an auto request was really served by the priority pool or fell back to standard is invisible unless you read usage.service_tier on the response. Because I was not recording it, I misread the cause of the slowdown for a long time.

So I wrapped every call in a thin helper that always logs which pool served it.

import logging
import anthropic
 
logger = logging.getLogger("claude")
client = anthropic.Anthropic()
 
def call(messages, *, tier="auto", label="unknown", **kwargs):
    """Set service_tier explicitly and record the pool actually used."""
    msg = client.messages.create(
        model="claude-haiku-4-5-20251001",
        max_tokens=1024,
        service_tier=tier,
        messages=messages,
        **kwargs,
    )
    served = msg.usage.service_tier  # "priority" / "standard" / "batch"
    # Make the gap between requested and served pool auditable later
    logger.info("tier_request=%s tier_served=%s label=%s in=%d out=%d",
                tier, served, label,
                msg.usage.input_tokens, msg.usage.output_tokens)
    return msg

Aggregating a single day of this log shows, as a number, how many requests at peak were tier_request=auto but tier_served=standard. In my environment, nearly 30% of auto requests were pushed out of the priority pool during the busiest hour. Once that lined up with the latency I was feeling, the cause was finally settled.

Pin background jobs to standard_only to protect the pool

Once observation confirms the contention, the fix is straightforward: send every non-user-facing call as standard_only. With the wrapper above, you only pass a different tier at each call site.

# Synchronous user request: allowed to use the priority pool
reply = call(user_messages, tier="auto", label="user_chat")
 
# Nightly / scheduled job: standard_only to preserve priority capacity
summary = call(batch_messages, tier="standard_only", label="nightly_summary")

When rolling this into production, here is the order I followed.

1. Add observation only. Leave service_tier unchanged and just log usage.service_tier for a day or two.
2. Check how much auto traffic falls back to standard at peak, and confirm the contention is real.
3. Switch background-job calls to standard_only one at a time. Touch the user-facing path last.
4. After each switch, confirm in the logs that the tier_served=priority rate for user-facing auto requests improved.

The point is not to flip everything at once. Convert the background jobs one by one, watching the priority-hit rate for user traffic recover each time. As a bonus, you learn which job was eating the most priority capacity.

Which workload belongs in which pool

The deciding axis is a single question: is a user waiting on this right now? I sort it out like this.

Tuning cost and latency per stage by varying the model or reasoning effort pairs well with the per-stage effort parameter article. service_tier decides which pool serves the request, while effort decides how hard the model thinks, so the two are orthogonal. Combined, you can assign user-facing traffic to the priority pool with enough effort, and background jobs to the standard pool with modest effort.

Common pitfalls

Expecting too much from standard_only without a Priority Tier commitment. If you have not committed to priority capacity, both auto and standard_only are effectively served by standard, so switching changes nothing. This setting only matters when you hold a finite priority pool and want to control how it is allocated. If you have not, moving async work to Batch has a far larger effect.

Reading standard_only as the "always slow" pool. When the standard pool has room, it returns quickly. Treat standard_only not as sacrificing latency, but as opting out of the competition for the priority pool.

Leaving everything on auto without watching usage.service_tier. Without observation, you cannot even notice the priority pool is exhausted. At minimum, log the pair of requested and served pool so peak behavior is traceable as a number.

Confusing peak latency with 529 errors. Being pushed out of the priority pool into standard is normal behavior and does not raise an error. Separately, when the standard pool itself gets congested, you may see 529. Handling congestion itself is a different topic, covered in handling Claude API 529 overloaded errors. service_tier is about pool allocation; 529 handling is about persistence under congestion.

One step to take first

Before changing any code, start by adding a single log line for usage.service_tier. The moment the gap between the pool you requested and the pool you were served becomes a number, where to direct your priority capacity decides itself. I misread the cause myself until I added that observation, so I would recommend measuring first.