Claude Stop Sequences: Patterns for Precise Output Control
November 4, 2026
How Claude stop sequences work, how to pass them in the API, and four patterns where they produce cleaner pipelines than max_tokens.
Claude stop sequences are strings you pass in the API call that halt generation the moment Claude outputs one of them. You can supply up to four. The response returns stop_reason: "stop_sequence" and the matched string in the stop_sequence field. Use them when you need a precise output boundary that max_tokens cannot express.
What Are Claude Stop Sequences, and How Do They Halt Generation?
When Claude generates a response, the API checks each new token against your stop_sequences list. The moment the output completes a match — the full string appears in the generated text — generation halts. No further tokens are produced, and the matched sequence is recorded in the response object.
This is fundamentally different from max_tokens, which limits total output length but cannot target a specific boundary in the text. A stop sequence fires based on content, not count. If Claude never outputs one of the strings, generation proceeds to end_turn exactly as if no stop sequences were set.
Stop sequences are case-sensitive and matched literally. The string "###" matches three consecutive hash characters and nothing else. Whitespace inside the string is part of the match, so "\n---\n" requires a newline on each side of the dashes.
How Do You Pass stop_sequences in the API Call?
The parameter name is stop_sequences and it takes an array of strings. Here is a minimal Python example using the Anthropic SDK:
import anthropic
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-4-8",
max_tokens=1024,
stop_sequences=["###", ""],
messages=[
{"role": "user", "content": "Generate a JSON object for a product."}
]
)
The same field works identically in the raw HTTP API as a JSON array:
{
"model": "claude-opus-4-8",
"max_tokens": 1024,
"stop_sequences": ["###", ""],
"messages": [{"role": "user", "content": "..."}]
}
Each string can be any sequence of characters: an XML-style closing tag, a markdown delimiter, a multi-character separator like "\n---\n", or a formatted prefix like "\n2.". If you pass an empty array the parameter has no effect.
How Does stop_sequence Appear in stop_reason and the Response Object?
The Messages API response always contains a stop_reason field that explains why generation stopped. When a stop sequence fires, that field equals the string "stop_sequence":
print(response.stop_reason) # "stop_sequence"
print(response.stop_sequence) # "###" — the string that matched
The companion field stop_sequence (singular) holds the exact string from your list that Claude matched. If stop_reason is anything other than "stop_sequence", the stop_sequence field is null.
This two-field design lets you branch your code without inspecting the content itself:
if response.stop_reason == "stop_sequence":
matched = response.stop_sequence # e.g. "###" or ""
# strip or process the boundary marker
elif response.stop_reason == "max_tokens":
# handle truncation
elif response.stop_reason == "end_turn":
# normal completion
The full set of stop_reason values the API can return is: end_turn, max_tokens, stop_sequence, tool_use, pause_turn, and refusal. Each signals a distinct condition your calling code can handle separately. Stop sequences and max_tokens are independent controls — if both could fire, whichever is reached first determines stop_reason.
When Should You Use stop_sequences Instead of max_tokens?
max_tokens answers one question: how many tokens can Claude produce? It caps output length without knowing anything about structure. stop_sequences answers a different question: at what textual boundary should Claude stop?
Use stop_sequences when:
- The output has a known terminal marker. If you instruct Claude to end its response with
</output>or---END---, a stop sequence catches that marker reliably regardless of response length. - You need to extract a single section from multi-part output. Stop before the second section begins rather than parsing the whole response after the fact.
- The correct length varies by content. A product description might need 20 words or 200 words. A stop sequence lets Claude decide naturally;
max_tokenswould either truncate short responses or under-budget long ones. - Post-processing cost matters. Stopping early saves output tokens. If Claude would naturally write three examples and you need only the first, stop after the first delimiter and pay for one, not three.
Use max_tokens when you need a hard ceiling on cost or latency regardless of content structure. The two parameters complement each other: set stop_sequences for the logical boundary and a generous max_tokens as a safety net.
What Are Four Patterns Where Stop Sequences Unlock Cleaner Code?
1. XML tag extraction
Instruct Claude to wrap its answer in <answer>…</answer> tags, then stop on "</answer>". You receive exactly the answer text with no preamble and no need to regex over the full response. The boundary is enforced at generation time, not at parse time.
response = client.messages.create(
model="claude-opus-4-8",
max_tokens=512,
stop_sequences=[""],
system="Wrap your answer in ... tags.",
messages=[{"role": "user", "content": question}]
)
2. Stopping before a second item in a list
If you ask Claude to generate numbered items and want only the first, stop on "\n2.". The response contains item one and nothing more. No splitting, no slicing — the boundary is enforced during generation, before any further tokens are written.
stop_sequences=["\n2."]
3. Separating chain-of-thought from the final answer
Prompt Claude to reason through a problem and then conclude with a known delimiter such as "ANSWER:". When you stop on that delimiter, you receive only the reasoning. When you omit the stop sequence and split on the delimiter in post-processing, you get both reasoning and answer. The delimiter is reliable in either mode because Claude emitted it; you are not guessing at structure.
4. Producing clean chunks for streaming pipelines
For incremental output you process turn-by-turn, instruct Claude to emit a known marker at natural content breaks. Stop on that marker, process the chunk, then continue in a new turn with the same conversation forwarded. Each turn produces a cleanly bounded unit rather than an arbitrary mid-token cut, and the calling code always knows exactly what it received.
What Does the CCA-F Exam Expect You to Know About Stop Sequences?
The Claude Certified Architect — Foundations (CCA-F) exam tests API response behavior directly. For stop sequences, expect questions in these areas:
- Field name distinction. The parameter is
stop_sequences(plural, array). The response field reporting which string matched isstop_sequence(singular). Confusing the two is a common distractor in scenario-based questions. - stop_reason values. When a stop sequence fires,
stop_reasonis exactly"stop_sequence". Know all six stop reason values and what triggers each:end_turn,max_tokens,stop_sequence,tool_use,pause_turn,refusal. - Null behavior. When
stop_reasonis not"stop_sequence", thestop_sequencefield isnull. The exam may present a partial response object and ask you to identify the value of this field for a givenstop_reason. - Limit and independence. The API accepts up to four stop sequences per request. Stop sequences and
max_tokensare independent — both can be set on the same request, and whichever fires first determinesstop_reason. - Relationship to end_turn. If none of the stop sequences are matched and the model finishes naturally,
stop_reasonis"end_turn"andstop_sequenceisnull. Stop sequences that are never triggered have no effect on the response.
The exam also covers how to interpret a full response object including usage, content blocks, and all stop_reason values, so understanding stop sequences in context with the rest of the response schema is what the questions test — not just the ability to recall a definition.
Reading this post builds conceptual fluency with stop sequences. Turning that into exam-ready recall is a different task — one that requires working through scenario-based questions where you identify the correct field value from a partial response object, not just match a term to a description. PlinthPrep's question bank covers API response behavior including stop sequences and stop_reason values in that format. Visit plinthprep.com to test whether you have genuinely understood it before exam day.
Plinth Prep is an independent study resource and is not affiliated with Anthropic.
Frequently asked questions
- What are Claude stop sequences?
- Claude stop sequences are strings you pass in the stop_sequences parameter that halt generation the moment Claude outputs one of them. The API accepts up to four strings per request. When a match occurs, generation stops immediately and the response includes stop_reason: "stop_sequence" plus the matched string in the stop_sequence field.
- What stop_reason value fires when a Claude stop sequence is matched?
- When Claude outputs one of the strings in your stop_sequences list, the response sets stop_reason to "stop_sequence". The companion field stop_sequence (singular) contains the exact string that triggered the stop. If no stop sequence fires, stop_reason is "end_turn", "max_tokens", "tool_use", "pause_turn", or "refusal" instead.
- When should you use stop_sequences instead of max_tokens in the Claude API?
- Use stop_sequences when output has a known terminal marker — an XML tag, a delimiter, a numbered item boundary — and correct length varies by content. max_tokens caps token count regardless of structure. Stop sequences fire based on content, letting Claude end naturally at a meaningful boundary rather than at an arbitrary count.
- What is the stop_sequence field in a Claude API response?
- The stop_sequence field is a string in the Messages API response that holds the exact stop sequence string that triggered the halt. It is only populated when stop_reason equals "stop_sequence"; in all other cases the field is null. It identifies which of the up to four supplied sequences caused generation to end.
- What does the CCA-F exam expect candidates to know about Claude stop sequences?
- CCA-F candidates should know the parameter name stop_sequences (array, up to four strings), the stop_reason value "stop_sequence", that the stop_sequence field (singular) holds the matched string and is null otherwise, and all six stop_reason values. Expect scenario-based questions presenting partial response objects and asking you to identify field values.