Privacy Levels
A privacy level decides which providers can serve your requests. You choose it for your account, for an API key, or for a single request, and each level includes everything in the ones before it.
| Level | min_privacy | What it means |
|---|---|---|
| Default | none | All providers, Default privacy applies |
| Protected | seller_private | Request content hidden from sellers |
| Zero retention | zero_retention | Providers don't retain request content |
| Confidential | confidential | Providers can't access request content |
min_privacy · noneWhat it means · All providers, Default privacy appliesmin_privacy · seller_privateWhat it means · Request content hidden from sellersmin_privacy · zero_retentionWhat it means · Providers don't retain request contentmin_privacy · confidentialWhat it means · Providers can't access request contentEach provider's level comes from our review of it. A level isn't a guarantee, and a provider's level can change.
Today only Protected has providers. Zero retention and Confidential aren't offered yet: while levels are in force, saving either is refused with 400 privacy_level_unavailable, and a request that asks for one is refused with 404 privacy_level_unavailable. min_privacy_levels_with_supply on GET /v1/buyer/preferences lists the levels on offer now. The ZDR labels on some offers are separate from privacy levels and don't put an offer at Zero retention.
What each level includes
| Default | Protected | Zero retention | Confidential | |
|---|---|---|---|---|
| Trusted providers only | No | Yes | Yes | Yes |
| Request content hidden from sellers | No | Yes | Yes | Yes |
| Providers don't retain request content | No | No | Yes | Yes |
| Providers can't access request content | No | No | No | Yes |
| Runs in a secure enclave | No | No | No | Yes |
On Default, your Routing settings decide whether providers outside the trusted list can serve you.
On every level
- Your IP address is hidden from sellers. Sellers and providers get your request from our servers, without your IP address. Some image and video results download straight from the provider, which then sees it.
- The seller's provider gets your request. We send it to the provider the seller listed, using the seller's account with that provider, and that provider's own policy decides what it keeps. Your privacy level decides which providers can serve you.
What Surplus keeps, and for how long, is in Security and privacy and the Privacy Policy.
Setting a level
There are three places to set a level. A request runs at the highest of the three, so a key or a single request can ask for a stricter level than your account, never a looser one.
| Where | Covers | How |
|---|---|---|
| The account | every key in the account | Buy › Privacy in the dashboard, or {"preferences": {"min_privacy": "<level>"}} on PUT /v1/buyer/preferences |
| A key | every request made with that key | the Privacy field when you create or edit the key, or scope.min_privacy on POST /v1/keys and PATCH /v1/keys/{id} |
| A request | that request only | "min_privacy": "<level>" in the request body |
{"preferences": {"min_privacy": "<level>"}} on PUT /v1/buyer/preferencesscope.min_privacy on POST /v1/keys and PATCH /v1/keys/{id}"min_privacy": "<level>" in the request bodyOnly members who can create API keys can change the account's level. An account save changes only the fields you send.
A key's level over the API
A key's level is part of its scope, not its preferences: min_privacy sent to PUT /v1/buyer/keys/{id}/preferences is refused with 400 invalid_min_privacy. PATCH /v1/keys/{id} with a scope replaces the key's whole scope, so send the scope you read from GET /v1/keys/{id} with min_privacy added, or the key loses its other limits. A scope without min_privacy keeps the key's level, and "min_privacy": null clears it. Send the scope you read as expected_scope too ({} if the key had none), and the save is refused with 409 key_scope_changed if the key's scope changed in the meantime. Send a budget change in its own request: expected_scope with budget is refused with 400 expected_scope_with_budget.
Writes to /v1/keys need an admin key (inf_admin_...) or a signed-in session. An ordinary API key gets 403.
curl -X PATCH $SURPLUS_BASE_URL/keys/$KEY_ID \ -H "Authorization: Bearer $SURPLUS_ADMIN_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "scope": {"providers_blocked": ["openrouter.ai"], "min_privacy": "seller_private"}, "expected_scope": {"providers_blocked": ["openrouter.ai"]} }'
When a level applies
A level applies only while privacy levels are in force, which GET /v1/buyer/preferences reports as min_privacy_available: true. While they're paused, a level on your account, a key or a request is ignored: requests are served as on Default, nothing is refused, and a new level can't be saved. If we briefly can't confirm that levels are paused, a saved level is applied.
A stricter level saved on the account or a key reaches every request within about 30 seconds, and the response to the save includes min_privacy_effective_at, the time it applies from. A level sent in the request body applies to that request at once, so send it when you need a level immediately.
curl $SURPLUS_BASE_URL/chat/completions \ -H "Authorization: Bearer $SURPLUS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-5.6-luna", "messages": [{"role": "user", "content": "hi"}], "min_privacy": "seller_private" }'
With the OpenAI Python SDK, pass it as extra_body={"min_privacy": "seller_private"}. Every inference endpoint accepts min_privacy, text and media, with one exception: while levels are in force, a transcription paid with x402 or MPP refuses it with 400 invalid_min_privacy, so send that request with an API key. none asks for no minimum, and while levels are in force a value that isn't one of the four names is refused with 400 invalid_min_privacy.
When nothing at your level serves a model
If nothing at your level serves a model, the request is refused, unless you have your own priority or fallback provider key for that model, which then serves it. It's never sent to a seller below your level.
| Code | Status | Meaning |
|---|---|---|
privacy_level_unavailable | 404 | No seller at your level serves this model. Lower the level where it's set (the error message says whether that's the account, the key or the request), or choose a model that sellers at your level serve. |
privacy_level_capacity_unavailable | 503 | Sellers at your level serve this model, but none can take the request right now. Retry shortly. |
privacy_level_settings_unavailable | 503 | Your account's level couldn't be read right now. Retry shortly. |
invalid_min_privacy | 400 | The min_privacy in the request, or stored on the key or account, isn't one of the four names, or was sent on a transcription paid with x402 or MPP. |
privacy_level_unavailableStatus · 404Meaning · No seller at your level serves this model. Lower the level where it's set (the error message says whether that's the account, the key or the request), or choose a model that sellers at your level serve.privacy_level_capacity_unavailableStatus · 503Meaning · Sellers at your level serve this model, but none can take the request right now. Retry shortly.privacy_level_settings_unavailableStatus · 503Meaning · Your account's level couldn't be read right now. Retry shortly.invalid_min_privacyStatus · 400Meaning · The min_privacy in the request, or stored on the key or account, isn't one of the four names, or was sent on a transcription paid with x402 or MPP.Saving a level on the account or a key is refused, and nothing changes, with 400 privacy_level_unavailable when no provider offers that level yet, 400 privacy_levels_not_enabled while privacy levels are paused, or 503 privacy_levels_mode_unavailable when we can't check right now (retry shortly).
Seeing the level that served you
A text, embeddings, image or audio response the marketplace served can carry an x-si-privacy-level header with the level of the offer that served it: none, seller_private, zero_retention or confidential. Video and music jobs don't carry it. The header can also appear while levels are paused, so check min_privacy_available to know whether your level is being applied.
What levels don't cover
- Your own provider keys. A request sent with your own priority or fallback key goes from our servers to that provider on your own account, under that account's settings. When your priority key can't take a request, it goes to the marketplace at your level.
- Provider Market. Calls to
/v1/resources/...use a seller's provider key directly and don't apply a level, so they're refused with404 privacy_level_unavailablewhile your key or account has a level above Default. - x402 and MPP payments. A request paid with x402 or MPP has no account or key settings, so only a
min_privacyin the request applies. While levels are in force, a transcription paid that way refusesmin_privacywith400 invalid_min_privacy.
Questions
Can I use different levels for different work?
Yes. Each API key can have its own level. Leave the account on Default, so everyday keys get the most sellers competing on price, and give a key for sensitive work a stricter level. A key can only ask for a stricter level than your account, never a looser one. Set it when you create or edit the key. A key with its own level counts as a restricted key, so it can't create or manage keys.
On Default, can a seller see my requests?
Your request goes to the provider the seller listed, using the seller's account with that provider. Some providers have a setting that keeps a copy of requests on that account. Our seller terms forbid turning it on, but on Default we can't technically rule it out. If you allow all sellers, not only trusted providers, some sellers run the endpoint themselves. On Protected and stricter levels, request content is hidden from sellers, based on our review of each provider.
Is a privacy level a guarantee?
No. Each provider's level comes from our review of it, and a level can change.
How is secret masking different from a privacy level?
A level decides which providers can serve your request. Secret masking changes the request itself: it replaces the API keys, private keys, seed phrases, passwords and tokens it detects in a text request with placeholders before the request leaves us, then puts your real values back in the reply, except in the model's reasoning. It only catches what it recognises, and it works with any level. Turn it on (beta) for the account or a key, or send X-SI-Mask-Secrets: on with one request. See the secret masking guide.