Claude API Few-Shot Examples: Best Practices Guide

Few-shot prompting means showing Claude a handful of input/output pairs before asking it to handle a new case. Instead of describing a task abstractly, you demonstrate it — and Claude pattern-matches the format, tone, and reasoning style from your examples. This matters because Claude API few-shot examples best practices aren't just "add examples and hope." Poorly structured examples can actively hurt output quality, waste tokens, or bias the model toward edge cases that don't represent your real traffic.

This guide covers how many examples to use, how to format them, where to place them in the request, and the mistakes that most often cause inconsistent results — whether you're calling the Claude API directly or through a proxy like SubToAPI.

Why Few-Shot Still Matters with Claude

Claude models are strong at following natural-language instructions, which tempts people to skip examples entirely. But for tasks with a specific output shape — structured extraction, classification labels, tone-matching, code style, JSON schemas — examples remove ambiguity that instructions alone can't. A single well-chosen example often does more work than three paragraphs of explanation.

Few-shot is especially valuable when:

• The output format is rigid (exact JSON keys, CSV columns, specific labels)
• The task has a "house style" that's hard to describe (support tone, legal phrasing, code conventions)
• You need Claude to generalize from edge cases rather than obvious ones
• Zero-shot responses have been inconsistent across similar inputs

How Many Examples to Use

There's no universal number, but in practice:

• 1–2 examples is enough for simple formatting tasks (e.g., "convert this sentence to title case")
• 3–5 examples works well for classification or extraction with a few categories
• 5–8 examples is a reasonable ceiling for most production prompts — beyond that, you're usually fighting diminishing returns and burning context

If you find yourself needing 15+ examples to get consistent behavior, that's a signal the task is underspecified, not that you need more examples. Tighten the instructions first, then re-test with fewer examples.

Structuring Examples with XML Tags

Claude was trained to pay close attention to XML-style tags, and they make few-shot blocks far easier to parse reliably than plain text or markdown lists. A consistent structure like this works well:

<examples>
  <example>
    <input>The product arrived broken and support never responded.</input>
    <output>{"sentiment": "negative", "category": "support"}</output>
  </example>
  <example>
    <input>Shipping was fast and the packaging was great.</input>
    <output>{"sentiment": "positive", "category": "shipping"}</output>
  </example>
</examples>

Keep the tag names identical across every example — <input>/<output> or <query>/<answer>, whatever you pick. Inconsistent tag naming is one of the most common silent failures: Claude still performs reasonably, but accuracy drops because the pattern is less clean.

Where to Put Examples in the Request

You have two main options when calling /v1/messages-style endpoints:

1. In the system prompt — good for examples that define a stable, reusable behavior (classification schema, output format) that doesn't change per request.
2. As early turns in the conversation — simulate a mini conversation history where the user asks and the assistant answers correctly, then let the real question follow.

For most API integrations, putting examples in the system prompt is simpler to maintain and cheaper on tokens if you're caching the prompt. Here's a minimal example against SubToAPI's Messages endpoint, which mirrors the standard Claude request shape:

curl https://api.subtoapi.app/v1/messages \
  -H "Authorization: Bearer $SUBTOAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4",
    "system": "You classify support tickets. Always respond with JSON only.\n\n<examples>\n<example><input>Refund never processed.</input><output>{\"category\":\"billing\"}</output></example>\n<example><input>App crashes on login.</input><output>{\"category\":\"bug\"}</output></example>\n</examples>",
    "messages": [
      {"role": "user", "content": "I was charged twice for the same order."}
    ]
  }'

See /docs/messages for the full request reference and /docs/quickstart if you're setting up your first API key.

Diversity and Coverage

Examples should cover the range of inputs you actually expect, not just the easy or obvious cases. If your real traffic includes short, ambiguous, or multi-topic inputs, include at least one example like that. A common mistake is writing examples that are all clean, well-formed, and unambiguous — then being surprised when production inputs (messy, short, sarcastic) get misclassified.

A good spread for a classification task:

• One clear-cut positive case
• One clear-cut negative case
• One ambiguous or borderline case
• One edge case (empty input, mixed signals, unusual format)

Keep Format Perfectly Consistent

Claude is sensitive to small inconsistencies in your examples — inconsistent punctuation, key ordering, or spacing in JSON outputs can leak into the model's responses. Before shipping a few-shot prompt, run your examples through a formatter or lint check so every output block is byte-for-byte consistent in structure.

Test Iteratively, Not Just Once

Few-shot prompts degrade silently as your task or data drifts. Treat your examples like code:

• Version them alongside your prompt
• Re-test against a held-out set of real inputs when you add or remove examples
• Watch token usage — few-shot blocks add up fast across high-volume endpoints, and usage metadata (available per request through SubToAPI's dashboard) helps you see the actual cost impact before and after changes

Combining Few-Shot with Tool Use

If your task also needs Claude to call a tool (say, a lookup function), keep the few-shot examples focused purely on the conversational/output pattern and let the tool schema itself define strict parameters — see /docs/tools for how tool definitions work. Mixing tool-call examples into a few-shot block usually adds more confusion than it resolves; the tool schema already constrains the output shape.

Streaming Considerations

If you're streaming responses (/docs/streaming), few-shot examples don't change the streaming behavior, but longer system prompts with several examples do slightly increase time-to-first-token since the model processes the full context before emitting. If latency is critical, trim examples to the minimum that reliably produces correct output.

questions

How many few-shot examples does Claude need for good accuracy? Usually 3–5 for classification or extraction tasks, and 1–2 for simple formatting. If you need more than 8–10, simplify the task instructions instead of adding more examples.

Should few-shot examples go in the system prompt or as conversation turns? Put them in the system prompt when the behavior is stable across requests — it's simpler to maintain and plays well with prompt caching. Use conversation turns only when you need to simulate a dynamic back-and-forth.

Can few-shot examples replace fine-tuning? For most prompting-adjustable tasks, yes — well-structured examples with clear formatting get you most of the consistency fine-tuning would provide, without the setup cost or lock-in.