Choosing an operating point

Three labels are worth choosing between today: np-2026-08-r4, the newest and the default, np-2026-08-r3, and np-2026-07-r2, which a caller had to pin explicitly starting from when the default moved to r4; see release notes. np-2026-07-r1 stays resolvable for work that cites it and is not a label to start on. This page describes what each label does, in terms you can see in a response. It does not rank them by quality.

We do not publish an accuracy comparison between operating points. We have not measured one at a scale that would justify a public claim, and a comparison made on our workloads would not transfer to yours in any case. Anyone telling you that one label is “better for retrieval” is describing an impression, not a published result.Choose by the behaviour described below, then validate on your own traffic before you switch. That is the only comparison that answers your question.

What differs, on the wire

Everything in this table is observable in a response you can produce yourself.

	`np-2026-07-r2`	`np-2026-08-r3`	`np-2026-08-r4`
Recall reporting	Reports nothing about its search.	Returns a `selection_recall` block (`version: "npsr-2026-08-r1"`) and a top-level `records_admitted`, and reports the passes it attempted in `format_metrics.attempted_recall_rungs`: one entry when it selects, or gives up, on the first pass; more when it widens the search.	Returns the same `selection_recall` block at `version: "npsr-2026-08-r2"` and `records_admitted`, plus four top-level fields: `task_kind`, `selection_strategy_used`, `support_contract_used` and `adapter_attempt_count`.
Observed when it will not select	Stands down: `records_selected: 0`, `fallback_used: true`, and no records come back.	Returns every record instead, with `selected[].reason: "full context fallback"` and `format_metrics.engine_fallback_reason: "recall_safe_full_context_fallback"`.	The same as r3: every record comes back, with the same `reason` and `engine_fallback_reason`.
What that costs	`usage.outcome: "stood_down"`, `charge_multiplier: "0"`. Not charged.	`usage.outcome: "pass_through"`, `charge_multiplier: "0"` when every record comes back with the token total and record count unchanged, which is what happens on the stand-down example below. A fallback that changes either is priced as `fallback` at `"1.0"`. The receipt’s `charge_multiplier` is the authoritative signal; see How billing works.	The same as r3.
Response shape	The fields documented in the API reference.	The same fields, plus the additions above. They are additive; see Versioning.	The r2 fields, `selection_recall`, `records_admitted`, the four top-level fields above, and further `format_metrics` entries (`selection_strategy_initial`, `selection_strategy_used`, `support_contract_used`, `adapter_attempt_count`, and `semantic_*` and `support_contract_resolution_version` stamps). On every worked example on this page r4 did not emit `format_metrics.capacity_cap_tokens`, which r3 does; optional `format_metrics` entries vary by label, so read them as optional.

Row two is the one that decides most migrations for a workload that leans toward standing down: see the stand-down case, where r2 returns nothing and r3 and r4 return your whole context instead, neither charged for it. It is not the only outcome on this page, though: the canonical request below is a case where all three labels find something worth selecting, and select different amounts of it. Whether either pattern holds across your traffic, and what it costs there, is a question only your traffic can answer, which is what the evaluation step is for.

selection_recall and records_admitted are additive response fields that np-2026-08-r3 and np-2026-08-r4 emit and np-2026-07-r2 does not; np-2026-08-r4 adds four more top-level fields. A client that follows the rule about ignoring unrecognised fields needs no change to accept them.

The same request under all three labels

This is the canonical billing-dispute request, unchanged except for budget.operating_point. It is a 30-record request now: the same billing dispute, plus support-desk distractors, enlarged specifically so a reader could see all three labels engage on it rather than only r2. Run it yourself and you will get these numbers.

{
  "policy_version": "np-2026-07-r2",
  "records_available": 30,
  "records_selected": 2,
  "tokens_before": 1775,
  "tokens_after": 136,
  "tokens_saved": 1639,
  "reduction_ratio": 0.9233802816901409,
  "fallback_used": false,
  "usage": { "outcome": "engaged", "charge_multiplier": "1.0" }
}

{
  "policy_version": "np-2026-08-r3",
  "records_available": 30,
  "records_selected": 5,
  "tokens_before": 1775,
  "tokens_after": 314,
  "tokens_saved": 1461,
  "reduction_ratio": 0.8230985915492958,
  "fallback_used": false,
  "usage": { "outcome": "engaged", "charge_multiplier": "1.0" }
}

{
  "policy_version": "np-2026-08-r4",
  "records_available": 30,
  "records_selected": 5,
  "tokens_before": 1775,
  "tokens_after": 314,
  "tokens_saved": 1461,
  "reduction_ratio": 0.8230985915492958,
  "fallback_used": false,
  "task_kind": "pointed",
  "selection_strategy_used": "fast",
  "support_contract_used": "generic",
  "adapter_attempt_count": 1,
  "usage": { "outcome": "engaged", "charge_multiplier": "1.0" }
}

All three engage on this request; none of them stands down or passes through. r2 selects the tightest set, the customer’s message and the credit policy (r-008, r-009); r3 and r4 select the same five records as each other, in the same order, for the same token arithmetic: those two plus the refund policy and its exceptions (r-004, r-005) and a prior agent turn (r-021). All three are charged at the full rate, because all three engaged.

r3 and r4 agree here down to the byte count, unlike on the stand-down example below, where they also agree with each other but differ from r2 in kind, not just in count. Do not read “r3 and r4 selected the same records” as a general rule: it is a property of this request, not a guarantee. Evaluate on your own traffic rather than assuming it transfers.

r3 and r4 both selected on the first recall pass; neither had to widen its search, so format_metrics.attempted_recall_rungs holds one entry on both. Their selection_recall blocks otherwise carry the shape the wire-differences table above describes, at version: "npsr-2026-08-r1" on r3 and "npsr-2026-08-r2" on r4:

{
  "selection_recall": {
    "version": "npsr-2026-08-r1",
    "operating_point": "np-2026-08-r3",
    "records_submitted": 30,
    "records_admitted": 30,
    "candidates_scored": 21,
    "candidates_above_floor": 5,
    "candidate_limit_hit": false,
    "weighted_term_coverage": 0.673469387755102,
    "excerpt_term_coverage": 0.5918367346938775,
    "rejection_counts": {
      "hard_entity_conflict": 0,
      "secret_payload": 0,
      "below_selection_floor": 16,
      "record_count_budget": 0,
      "token_budget": 0,
      "excerpt_coverage_loss": 0
    },
    "evidence_confidence_score": 1.0
  },
  "format_metrics": {
    "attempted_recall_rungs": [
      { "candidate_limit": 250, "min_selection_score": 8.0, "max_selected_records": 18, "max_selected_tokens": 900 }
    ]
  }
}

Read the observable difference plainly, without a story about why: on this request r2 selected two records; r3 and r4 each selected the same wider set of five. None of the three needed to widen its search to reach its conclusion, which is itself informative: a request this well-supported does not exercise the multi-rung recall path at all. The stand-down example below is where r3 and r4’s behaviour actually diverges from r2’s.

And a request where all three agree

Forty filler records and one that answers the question, at a 600-token budget. Build it yourself:

filler = [
    {
        "id": f"f-{i:03d}",
        "kind": "external_data",
        "title": f"Ops log entry {i}",
        "source": "ops-wiki",
        "text": (
            f"Routine maintenance window {i} completed without incident. Disk "
            "utilisation nominal, replication lag under one second, no operator "
            "intervention required. Backups verified against the nightly checksum "
            "manifest and archived to cold storage."
        ),
    }
    for i in range(40)
]
needle = {
    "id": "n-001",
    "kind": "external_data",
    "title": "Incident 7742 postmortem",
    "source": "ops-wiki",
    "text": (
        "Incident 7742: the payment reconciliation job double-charged 218 accounts "
        "on 2026-06-14 because the idempotency key was derived from the batch id "
        "rather than the transaction id. Remediation refunded all 218 accounts "
        "within 72 hours."
    ),
}

payload = {
    "records": filler[:20] + [needle] + filler[20:],
    "task": {
        "prompt": "What caused incident 7742 to double-charge accounts, "
                  "and how many accounts were affected?"
    },
    "budget": {"max_context_tokens": 600, "operating_point": "np-2026-07-r2"},
    "return_per_record": True,
}

All three labels select n-001 and nothing else. All three report records_selected: 1, tokens_before: 2418, tokens_saved: 2360 and reduction_ratio: 0.9760132340777502, and all three engage rather than fall back, at charge_multiplier: "1.0". The selected set and the token arithmetic are identical across the three. The responses also differ in the additive fields r3 and r4 add, in selected[].reason, selected[].score and gate.reason, and r4 inserts a newline in both selected[].excerpt and rendered_context. The reason strings are open-ended, and none of these differences changes the selected record. We include this deliberately. It is the case a “the newer label is stronger at long sparse retrieval” story would predict a difference on, and there is none. Do not pick a label on a story; pick it on your own traffic.

A stand-down is a correct outcome

The most common surprise on a first integration is a response that saved nothing. Usually nothing is wrong. Needlepath selects when there is a selection worth making. Two ordinary situations produce no savings:

Your context already fits

If everything you sent fits comfortably inside max_context_tokens, there is no pressure to relieve, and cutting would only lose you information for no gain. You get your context back. The three-record example does exactly this.

Nothing stood out

If no record scores meaningfully above the others against your task, there is no defensible subset to choose. Returning an arbitrary one would be worse than returning all of them.

What that looks like under each label

Three small records, a 4000-token budget, and nothing under pressure. This is the three-record example, sent unchanged to all three labels. One of the three is sent with importance: 0.0, the lowest priority the signal has; it comes back on r3 and r4 exactly like the other two.

{
  "policy_version": "np-2026-07-r2",
  "rendered_context": "Relevant State: none selected.",
  "selected": [],
  "records_available": 3,
  "records_selected": 0,
  "tokens_before": 49,
  "tokens_after": 0,
  "tokens_saved": 0,
  "reduction_ratio": 0.0,
  "fallback_used": true,
  "gate": { "engaged": false, "reason": "standdown:insufficient_candidates" },
  "usage": { "outcome": "stood_down", "charge_multiplier": "0", "input_tokens": 65 }
}

{
  "policy_version": "np-2026-08-r3",
  "records_available": 3,
  "records_selected": 3,
  "tokens_before": 45,
  "tokens_after": 45,
  "tokens_saved": 0,
  "reduction_ratio": 0.0,
  "fallback_used": true,
  "gate": { "engaged": false, "reason": "standdown:insufficient_candidates" },
  "usage": { "outcome": "pass_through", "charge_multiplier": "0", "input_tokens": 65 }
}

{
  "policy_version": "np-2026-08-r4",
  "records_available": 3,
  "records_selected": 3,
  "tokens_before": 45,
  "tokens_after": 45,
  "tokens_saved": 0,
  "reduction_ratio": 0.0,
  "fallback_used": true,
  "gate": { "engaged": false, "reason": "standdown:source_support_missing" },
  "usage": { "outcome": "pass_through", "charge_multiplier": "0", "input_tokens": 65 }
}

Same request, same conclusion that there is nothing worth selecting, and one difference in what comes back: r2 returns nothing, r3 and r4 return all three records unchanged, including the one sent with importance: 0.0. A full-context fallback does not filter by importance; nothing is dropped for any reason on that path. None of the three is charged: stood_down on r2 and pass_through on r3 and r4 both carry charge_multiplier: "0". All three hand you a context you can send. It is still worth measuring on your own traffic before switching: a fallback that changes the token total is charged, and how often that happens is a property of your workload. Both are 200 responses. Neither is an error, and neither means the integration is broken. Read them like this:

You see	It means	Do
`fallback_used: true` with `records_selected: 0`	Stood down. Nothing selected.	Send your original context. Under r2 this is `charge_multiplier: "0"`.
`fallback_used: true` with every record returned	r3 or r4 declined to narrow and gave you everything.	Send your original context. Priced as `pass_through` (not charged) when every record came back with the token total and record count unchanged, and as `fallback` at the full rate otherwise. Read `usage.charge_multiplier`.
`tokens_saved: 0` on small requests	The request was never under budget pressure.	Nothing. Consider not calling at all for contexts that already fit.

If most of your traffic stands down, that is a signal about the workload rather than a fault: you are probably calling on contexts that already fit. The homepage has the fit criteria. Measure it with shadow mode before you tune anything.

Evaluating a newer label on your own traffic

Nothing below requires a code change beyond the value of one string.

Mirror real traffic, do not switch it

Keep production pinned to the label it runs today. Send a copy of the same requests with budget.operating_point set to the label you are evaluating, and discard the result. This is exactly the shadow mode pattern, with the label as the only variable. Wrap it so a failure cannot touch the real call.Both calls are metered, and each is billed according to its own receipt’s charge_multiplier. Sample if that matters: a fixed fraction of requests, chosen by a stable uniform hash of request_id rather than by content, keeps the comparison representative and reduces the cost in proportion.

Compare the pairs, not the aggregates

Log both responses against the same request_id and compare per request:

Record	Why
`records_selected` and `selected[].record_id`	Whether the two labels chose differently at all.
`tokens_saved`	What the switch would cost or save you in prompt size.
`fallback_used` and `usage.outcome`	How often the newer label returns everything where the production label stood down, and how often it declines where the production label selected. This is the number that decides most migrations.
`usage.charge_multiplier`	Requests whose price differs between the two labels.
`policy_version` and `build_id`	So the week is attributable. See what a label pins.

An aggregate savings figure will not tell you whether an answer degraded. The per request dropped-record list will.

Spot-check the disagreements

Pull the requests where the two labels selected different records and read them. That set is normally small, and it is the entire evidence base for the decision.

Switch one string

When you are satisfied, change budget.operating_point to the label you evaluated in production. Nothing else in the request or the response handling changes.

Rolling back

Set budget.operating_point back to the label production ran before the switch: whatever label you pinned production to before you started evaluating a new one. The warning below covers the case where there was nothing pinned to go back to; the default itself has moved once already (np-2026-07-r2 to np-2026-08-r4), which is exactly the scenario it describes. That is the whole procedure, and it works because labels are immutable: the label you left applies today the same configuration it applied when you left it, so going back is not a migration, it is a one-word revert. There is no deprecation to race and no deadline attached to any published label. Every published label stays resolvable. What rollback restores is the configuration, which is the thing that changed when you switched labels. It does not rewind the engine build, and it does not need to: see what a label pins.

Rollback only works if you pinned in the first place. A caller that omits budget.operating_point inherits the server default, has nothing to revert to, and cannot tell from its own code which configuration produced last week’s results. Pin the label even when you are pinning the one that is already the default.

Operating points

What a label pins, what it cannot, and why it is opaque.

Shadow mode

The measurement pattern this page’s evaluation step is built on.

How billing works

What each usage.outcome costs.

Errors

Reading a stand-down in full.

Get started

Release notes

How selection works

Running it in production

Billing

Integrations

Choosing an operating point

What differs, on the wire

The same request under all three labels

And a request where all three agree

A stand-down is a correct outcome

What that looks like under each label

Evaluating a newer label on your own traffic

Rolling back

Next

Operating points

Shadow mode

How billing works

Errors

​What differs, on the wire

​The same request under all three labels

​And a request where all three agree

​A stand-down is a correct outcome

​What that looks like under each label

​Evaluating a newer label on your own traffic

​Rolling back

​Next

Operating points

Shadow mode

How billing works

Errors

What differs, on the wire

The same request under all three labels

And a request where all three agree

A stand-down is a correct outcome

What that looks like under each label

Evaluating a newer label on your own traffic

Rolling back

Next