Antimatter

POST/api/account/shadowSigned in session

As POST /v1/shadow, with key_id choosing the key (null is every personal key). Same origin only. A 404 at every path while the operator has not turned shadow testing on.

Request body

application/json, required

Request body fields
Field	Type	What it is
name	string	At most 100 characters.
modelrequired	string	The model whose traffic is shadowed: captured requests this model answered with a 2xx. At most 200 characters.
candidatesrequired	array of string or "suggest"	1 to 5 model ids, or "suggest" for the cheapest comparable models (no dearer on either rate, the original's context, its tool calling and JSON held).
suggest_count	integer	From 1 to 5.
sample_raterequired	number	The share of captured requests replayed, at most 0.1. A capture is in the sample by a hash of the test and its trace id. At most 0.1.
daily_caprequired	integer	The most captured requests sampled in one UTC day, at most 1000. From 1 to 1000.
monthly_ceiling_microsrequired	integer	Required. The most every replay and its comparison may be billed in a UTC month; each replay's worst case is held against what is left before it is sent. From 1 to 9007199254740991.
compare	object	auto (JSON field by field, else normalized text) unless set; embedding with embedding_model (cosine at cosine_threshold, 0.9 unless set); judge with a judge_model you name; suite with suite_id and suite_budget_micros.
compare.methodrequired	string	One of "auto", "embedding", "judge", "suite".
compare.embedding_model	string	At most 200 characters.
compare.judge_model	string	At most 200 characters.
compare.suite_id	string	At most 100 characters.
compare.suite_budget_micros	integer	At most 9007199254740991.
compare.cosine_threshold	number	From 0 to 1.
threshold	number	The agreement the 95% interval's lower end must reach for a candidate to be ready, 0.9 unless set. From 0 to 1.
min_samples	integer	Comparisons a candidate needs before it is ready, 30 unless set. From 10 to 100000.
key_id	integer or null	The dashboard only: the key whose traffic is tested, or null for every personal key. A key over /v1/shadow tests its own.

Example

{
  "model": "antimatter/auto",
  "candidates": [
    "string"
  ],
  "sample_rate": 0,
  "daily_cap": 1,
  "monthly_ceiling_micros": 1
}

Answer 201

The test.

Fields of the 201 answer
Field	Type	What it is
id	string	shd_ and 24 hex digits.
object	"shadow.test"
name	string
model	string
scope	string	One of "key", "account".
key_id	integer or null
status	string	One of "active", "stopped".
stopped_reason	string or null
held_until	integer or null	Unix seconds: the month's ceiling is reached, nothing runs before this.
sample_rate	number
daily_cap	integer
sampled_today	integer
monthly_ceiling_micros	integer
month_spent_micros	integer
month_reserved_micros	integer
spent_micros	integer
compare	object
threshold	number
min_samples	integer
candidates	array of object
candidates[].model	string
candidates[].suggested	boolean
switch	object or null	The switch standing, if any: the candidate and the keys it routes.
switch.to	string
switch.key_ids	array of integer
switch.switched_at	integer
switch.auto	boolean	Made by the gateway under auto savings.
auto	object	Auto savings: whether the gateway may switch this test itself once a candidate is ready.
auto.enabled	boolean
auto.enabled_at	integer or null
auto.switched_at	integer or null
auto.switched_to	string or null
auto.off_reason	string or null	Why it is off when it was on: turned off, reverted, or why a switch failed.
savings	array of object	The newest weekly reports (Monday to Monday, UTC) of what a standing switch saved: the requests it moved, read from their usage rows, what they were billed, and what they would have cost on the original at the report's measured cost ratio.
savings[].week_start	integer
savings[].from	string
savings[].to	string
savings[].auto	boolean
savings[].requests	integer
savings[].cost_micros	integer
savings[].baseline_micros	integer
savings[].saved_micros	integer
savings[].ratio	number
created_at	integer
updated_at	integer

Errors

400OpenAI shaped error.
401OpenAI shaped error.
403OpenAI shaped error.
404OpenAI shaped error.
409OpenAI shaped error.

Every error answers in one shape, with its type, code and the field it names. The whole list is in the docs' Errors section.