Claude API Sampling: Temperature, Top-P, Top-K, Stop (2026)

Claude API exposes 5 sampling parameters that control output style: temperature (0.0-1.0, default 1.0), top_p (0.0-1.0), top_k (1-500), stop_sequences (up to 4 strings), and max_tokens (required). Defaults work for chat; for production you tune them. Lower temperature = more deterministic. Higher top_k = more vocabulary. stop_sequences = early termination markers. Most teams over-tune top_p/top_k when only temperature matters. This guide explains each parameter, when to use it, real benchmark numbers, and the 3 mistakes that waste tokens.

For Claude API basics see the Python tutorial. For cost-optimal model selection see Haiku vs Sonnet vs Opus.

The 5 Parameters at a Glance

The 80/20 rule: temperature and max_tokens are the 2 you tune. top_p/top_k are escape hatches you rarely need.

Temperature: The One That Matters

# Deterministic output — pick the same answer every time
response = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=512,
    temperature=0.0,  # nearly deterministic
    messages=[{"role": "user", "content": "Extract the price from: ..."}]
)

# Creative output — varied responses across calls
response = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=512,
    temperature=1.0,  # default — varied
    messages=[{"role": "user", "content": "Write 3 ad headlines for ..."}]
)

Use temperature=0 for: code generation, structured extraction, classification, math, function calling. You want consistency across runs.

Use temperature=0.5-0.7 for: technical writing, summaries, balanced agentic decisions.

Use temperature=1.0 for: creative writing, brainstorming, marketing copy, conversation.

Real-world impact (1,000 runs, same prompt)

For structured tasks like JSON mode, temperature=0 + tool_choice gives the highest reliability.

Top-P (Nucleus Sampling)

top_p limits sampling to tokens whose cumulative probability reaches p. At 0.9, only the most likely tokens that together cover 90% of probability mass are considered.

response = client.messages.create(
    temperature=0.7,
    top_p=0.9,  # cut off long tail
    ...
)

When to use top_p: when you want creative output but need to clamp the rare-token tail (avoid weird words). Combine with mid temperature (0.5-0.8).

Anthropic recommendation: tune temperature OR top_p, not both. Most teams should stick with temperature alone.

Top-K (Vocabulary Limit)

top_k limits sampling to the k most likely tokens at each step. At 5, only the 5 most likely next tokens can be chosen.

response = client.messages.create(
    temperature=0.8,
    top_k=40,  # restrict vocabulary
    ...
)

Use cases: extreme content filtering, structured tasks where you want only "obvious" continuations. Default (effectively unlimited) is right for 99% of cases.

Stop Sequences

Up to 4 strings that, if Claude generates them, cause immediate stop:

response = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=2048,
    stop_sequences=["\n\nHuman:", "\n\n###", "END_OF_ANALYSIS"],
    messages=[{"role": "user", "content": "Analyze X. End with END_OF_ANALYSIS"}]
)

# Check why it stopped:
print(response.stop_reason)  # "stop_sequence" | "end_turn" | "max_tokens"
print(response.stop_sequence)  # which stop string triggered (if applicable)

Use stop_sequences for:

• Structured output with clear delimiters
• Preventing Claude from continuing past the answer
• Early termination in long-generation tasks

Cost benefit: stops generation early → fewer output tokens → cheaper. A 2K-token cap with a stop sequence at 500 saves 75% on that response.

Max Tokens: The Biggest Cost Lever

Required. Sets the upper limit on output tokens. Lower max_tokens = lower cost ceiling, even if Claude actually outputs less.

# Bad — pays for up to 4096 even if response is 200 tokens
response = client.messages.create(max_tokens=4096, ...)

# Good — explicit ceiling for the task
response = client.messages.create(max_tokens=256, ...)  # classification task

Realistic ceilings:

• Classification: 50-100
• Short summary: 200-500
• Code generation (single function): 800-1500
• Long-form article: 2000-4000
• Full document generation: 4000+

You're not charged for the cap — you're charged for actual output. But setting max_tokens lower prevents runaway generation (Claude stuck in a loop, infinite list, etc.).

For more on cost levers see Claude API Cost Optimization.

The 3 Mistakes That Waste Money

1. max_tokens set to "safe high number"

max_tokens=4096 "just in case" causes:

• Latency: even if Claude outputs 200 tokens, the API may take longer to confirm there's nothing more
• Runaway cost: a bug causes Claude to fill the buffer with garbage, you pay for 4000 wasted tokens
• Fix: set max_tokens to realistic 1.5x ceiling

2. Both top_p AND temperature tuned

Tuning both creates non-obvious interactions. Pick one. Anthropic's own docs recommend temperature.

3. temperature=1.0 for extraction tasks

Default is 1.0. For data extraction, you want 0.0. Default temperature wastes ~10% of structured-output budget on hallucinations.

# WRONG
response = client.messages.create(
    messages=[{"role": "user", "content": "Extract names from: ..."}]
)  # uses temperature=1.0

# RIGHT
response = client.messages.create(
    temperature=0,
    messages=[...]
)

Combining Parameters: Real Production Settings

Code generation agent

{
  "model": "claude-sonnet-4-5",
  "temperature": 0.2,
  "max_tokens": 2048,
  "stop_sequences": ["```\n\n##"]  # stop after code block
}

Customer support

{
  "model": "claude-sonnet-4-5",
  "temperature": 0.7,
  "max_tokens": 600,
  "stop_sequences": ["Customer:"]  # don't keep replying for the user
}

Data extraction

{
  "model": "claude-haiku-3-5",
  "temperature": 0,
  "max_tokens": 1024
}
# Optionally: tool_choice forced for guaranteed JSON

Creative writing

{
  "model": "claude-sonnet-4-5",
  "temperature": 1.0,
  "max_tokens": 2500
}

Streaming + Parameters

Sampling parameters work identically in streaming. The temperature and stop_sequences are evaluated per-token by Claude before each token is emitted to the stream.

with client.messages.stream(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    temperature=0.3,
    stop_sequences=["DONE"],
    messages=[...]
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

See Claude API Streaming Guide for streaming patterns.

Frequently Asked Questions

Should I tune top_p or temperature?

Pick temperature. Anthropic's documentation, internal benchmarks, and most production deployments use temperature as the single sampling knob. Use top_p only if temperature alone doesn't give the variability you need.

What's the lowest temperature for "deterministic" output?

temperature=0 gives near-determinism but not 100%. Floating-point precision and GPU non-determinism produce ~0.1% variability across runs. For absolute determinism use a seed (when Anthropic adds seed support) or run multiple calls and take majority vote.

Does temperature affect token cost?

No. Token cost is per input/output token. Temperature only affects which tokens are sampled, not how many.

What's the practical max_tokens limit?

Per the API, up to 200,000 (matching the context window). In practice, Claude's training caps output at ~8K-16K tokens for coherent responses. Long-form tasks should set 4-8K and chain multiple calls if more is needed.

Can stop_sequences trigger mid-word?

No. Stop sequences match token boundaries. If your stop is "END" and Claude generates "ENDING", it does not stop. Use distinctive multi-token strings like "###END###" to avoid false negatives.

Master Claude API Production Settings

Cost Optimization Masterclass ($59) — production parameter playbook for 30+ deployment patterns: classification, extraction, agents, RAG, creative. Tuned settings save 40-60% on output token spend.