runs

GET /compute-classes

List training compute classes

The training compute classes available to the resolved project (WP-M10 req 6), cheapest first, each with per-project available (best-effort pool capacity/quota), plan_allowed (the WP-B2 plan gate; when absent, all non-experimental classes are allowed), cost_hint and fallback_to. Consumed by the console run-launch selector.

Operation ID: listComputeClasses · Service: gateway-api

Authentication

• apiKey (http (bearer)) — Project API key (003 §2): tsk_live_… or tsk_test_… in Authorization: Bearer. Scoped to exactly one project + environment; scopes are a subset of ingest, read, admin. Keys are stored hashed and shown once at creation.
• consoleSession (http (bearer)) — Console session (003 §2): Identity Platform JWT. Data-plane calls add X-Tessera-Project + X-Tessera-Environment headers, validated against org membership.

Responses

Status	Schema	Description
200	ComputeClassList	The project's compute classes.
default	ErrorEnvelope	Error response (003 §1). Every non-2xx response uses this envelope; the HTTP status matches error.code. Rate-limited requests get 429 resource_exhausted with retry_after_seconds and a Retry-After header; the X-RateLimit-* headers ride on EVERY response, success or error (003 §1; plan-driven per API key + endpoint class — WP-B2). A 503 unavailable carries retry_after_seconds too for a lock-wait timeout (SQLSTATE 55P03), a rule preview at capacity (preview_capacity_exhausted), or a label preview during which the erasure of every entity holding its censor clock began (label_preview_clock_entity_erased): how long to wait before retrying.

GET /runs

List training runs

Training runs of the resolved project + environment, newest first (cursor pagination, 003 §1). Optional filters combine with AND and apply before page-size limits. Date bounds select created_at instants; a lower bound greater than or equal to the upper bound is invalid_argument. Restart pagination when filters change. Omitting filters preserves existing list behavior and the response representation. Annotations (TES-034) appear only with the explicit include_annotations=true opt-in; default responses never gain annotation or reusable-configuration fields. Multi-node runs (WP-M6) are kept out of the page unless the explicit include_multi_node=true opt-in is given, so installed SDKs that validate the closed v1 TrainingRun never meet one; read their topology with GET /runs/\{run_id\}/topology.

Operation ID: listRuns · Service: gateway-api

Authentication

• apiKey (http (bearer)) — Project API key (003 §2): tsk_live_… or tsk_test_… in Authorization: Bearer. Scoped to exactly one project + environment; scopes are a subset of ingest, read, admin. Keys are stored hashed and shown once at creation.
• consoleSession (http (bearer)) — Console session (003 §2): Identity Platform JWT. Data-plane calls add X-Tessera-Project + X-Tessera-Environment headers, validated against org membership.

Parameters

Name	In	Required	Type	Description
created_at_gte	query	no	string	Inclusive created_at lower bound (RFC3339 instant, normalized to UTC microseconds). If created_at_lt is supplied, this must precede it; otherwise return invalid_argument using the standard error envelope.
created_at_lt	query	no	string	Exclusive created_at upper bound (RFC3339 instant, normalized to UTC microseconds). If created_at_gte is supplied, this must follow it; otherwise return invalid_argument using the standard error envelope.
cursor	query	no	string	Opaque pagination cursor from a previous response's next_cursor.
dataset_id	query	no	string	Exact dataset ID recorded on the run. A missing or out-of-scope ID produces an empty page, never a cross-project or cross-environment lookup.
include_annotations	query	no	boolean	Explicitly opt into each item's annotations (TES-034). Omitted or false preserves the existing representation without annotations; true adds them to every item, including never-annotated items (revision 0). Retain this option on subsequent cursor requests.
include_multi_node	query	no	boolean	Explicitly opt into multi-node runs (WP-M6). Omitted or false keeps every multi-node run (trainer.nodes \> 1 at creation or after a resume) out of the page, so installed SDKs that validate the closed v1 TrainingRun never meet one; true adds them in the same TrainingRun representation, whose trainer.world_size is the ranks per node when the total exceeds the v1 bound of 8 (the nodes, total world_size and per-node status are GET /runs/\{run_id\}/topology). Retain this option on subsequent cursor requests.
label_id	query	no	string	Exact membership in the resource's stored label-ID set. Empty-label resources do not match. A missing or out-of-scope ID produces an empty page without resolving another tenant's label. Combine with other filters before cursor pagination.
limit	query	no	integer	Page size (cursor pagination, 003 §1). Maximum 200.
status	query	no	string	Exact run lifecycle status; applied before cursor pagination.
tag	query	no	string	Exact whole-tag membership in the resource's annotation tags (TES-034; see ExperimentTag). Never a substring or serialized-text match. Resources without annotations do not match; an unused tag produces an empty page. Combine with other filters (AND) before cursor pagination. A malformed tag is invalid_argument.

Pagination

Cursor pagination (003 §1): pass limit (max 200) and cursor; the response is the pagination envelope — data plus next_cursor (null on the last page).

Responses

Status	Schema	Description
200	TrainingRunPage	Page of training runs, newest first.
default	ErrorEnvelope	Error response (003 §1). Every non-2xx response uses this envelope; the HTTP status matches error.code. Rate-limited requests get 429 resource_exhausted with retry_after_seconds and a Retry-After header; the X-RateLimit-* headers ride on EVERY response, success or error (003 §1; plan-driven per API key + endpoint class — WP-B2). A 503 unavailable carries retry_after_seconds too for a lock-wait timeout (SQLSTATE 55P03), a rule preview at capacity (preview_capacity_exhausted), or a label preview during which the erasure of every entity holding its censor clock began (label_preview_clock_entity_erased): how long to wait before retrying.

POST /runs

Start a training run

Validates the request against the dataset build (must exist, be succeeded, and carry no error-severity violation report entry — else 400 failed_precondition; warn-level entries such as label_temporal_gate are findings, not refusals: the run starts and its run.create audit event lists them as dataset_findings), the requested labels (must be a subset of the dataset's labels) and the 005 §4 ModelConfig bounds (invalid tier/overrides → 400 invalid_argument), assembles the content-addressed run config (https://spec.tessera.dev/schemas/run_config.json — WP-M3 req 2: no wall-clock or RNG inputs), persists a runs row in status queued and creates one Kueue-queued GKE Job on the gpu-train pool (queue training, 001 §4). A request resolving to an existing (project, config_fingerprint) is idempotent: non-terminal runs return their run_id unchanged. A run that a training study created (WP-M27) is never returned to an ordinary request: such a request gets its own run (ERRATA 2026-10-15, ruling 9). Optional expected_config_fingerprint (TES-034 exact reuse) is a precondition checked after config assembly and before deduplication, persistence or launch: a different assembled fingerprint returns 400 failed_precondition whose pin_drift details name every drifted config field, and no run is created or launched. Multi-node runs (WP-M6, trainer.nodes \> 1, world_size up to 64) launch one Indexed Job spanning every node; a multi-node trainer whose global_batch_tokens has no exact decomposition over world_size ranks within the micro-batch bounds, an uneven or oversized topology, or a dataset with fewer non-empty train shards than ranks (too_few_shards) is refused with 400 invalid_argument here, never on the cluster. Single-node requests (any world_size, at most 8) keep their WP-M3 packing and fingerprints unchanged. The response is the compatibility-frozen v1 TrainingRun for every run: it never carries nodes or per-node status, and a multi-node run whose total world_size exceeds the v1 bound of 8 reports its ranks per node in trainer.world_size — read GET /runs/\{run_id\}/topology for the topology and the replay body. A WP-M17 hazard dataset (its manifest carries a hazard block) gives the run its hazard heads from the dataset, never from an override, and requires the observation-time model it was built for: overrides must set observation_time: true and readout: last_event, else 400 failed_precondition.

Operation ID: createRun · Service: gateway-api

Authentication

• apiKey (http (bearer)) — Project API key (003 §2): tsk_live_… or tsk_test_… in Authorization: Bearer. Scoped to exactly one project + environment; scopes are a subset of ingest, read, admin. Keys are stored hashed and shown once at creation.
• consoleSession (http (bearer)) — Console session (003 §2): Identity Platform JWT. Data-plane calls add X-Tessera-Project + X-Tessera-Environment headers, validated against org membership.

Parameters

Name	In	Required	Type	Description
Idempotency-Key	header	no	string	Idempotency key accepted by all POSTs (003 §1): 24 h dedup window, keyed per project. POSTs that are reads (batchSlotScores, scoreSlotEvent, deriveSlotBands, validateSourceRawPreset, sampleSource, watchEventFeedHeads and the preview operations: previewSourceMapping, previewCatalogMapping, previewLabel, previewPatternLabel, previewMarker, previewDatasetEligibility, previewSlotAudience, previewSharedCheckpointImport, previewSlotAtlasInquiry) accept the key but never replay a stored response: a retry with the same key is executed again (and metered again) against current data. A stored response that names an entity is removed when that entity is erased. A key that already answered answers only a retry of the request that stored its response: the same caller, environment, operation, path, query, scoping headers and body (a JSON body by its content, a gzip body by its inflated content). The same key with any other request is 409 already_exists with details[0].reason idempotency_key_reused, and that request is not run. The window holds no in-flight marker: two first requests sent at once can both run. A response stored by a release before this rule cannot be matched to its request and is refused the same way until it expires; send the request again with a new key. A body over 8 MiB (ingest: over its 5 MiB request limit) is run and its response is not stored. The ingest batch (POST /events) is the exception, except for an application's credentials: under a key that answered another batch it runs again, uncached, and its events' ids deduplicate them; so it does when its stored response cannot be checked. The operations that return a one-time secret store their response sealed: the stored copy opens only for the same key and credential, and one that cannot be opened is 409 idempotency_key_reused. While the server cannot check a stored response (it cannot read the key that checks it, for one), the request is 503 unavailable with Retry-After: retry with the same key. An operation whose handler claims the key itself answers the same 503, before it runs, while the key-hash pepper cannot be read; any other request sent with a key runs meanwhile, and its response is not stored.

Idempotency

This operation accepts an Idempotency-Key header (003 §1): within 24 hours, keyed per project and caller, a retry of the same request gets the first response, and the same key with another request is 409 already_exists (idempotency_key_reused). See the Idempotency-Key parameter for the exceptions.

Request body

TrainingRunRequest

Responses

Status	Schema	Description
200	TrainingRun	The training run record (new or idempotent existing).
default	ErrorEnvelope	Error response (003 §1). Every non-2xx response uses this envelope; the HTTP status matches error.code. Rate-limited requests get 429 resource_exhausted with retry_after_seconds and a Retry-After header; the X-RateLimit-* headers ride on EVERY response, success or error (003 §1; plan-driven per API key + endpoint class — WP-B2). A 503 unavailable carries retry_after_seconds too for a lock-wait timeout (SQLSTATE 55P03), a rule preview at capacity (preview_capacity_exhausted), or a label preview during which the erasure of every entity holding its censor clock began (label_preview_clock_entity_erased): how long to wait before retrying.

GET /runs/{run_id}

Get a training run

Status (queued | running | succeeded | failed | cancelled), pinned fingerprints, retained checkpoint URIs, best_val_loss and — once succeeded — the created model_id (002 §9 ModelVersion in status training). Another tenant's run id is indistinguishable from a missing one (404 not_found, 003 §3). A multi-node run (WP-M6) is returned in this same compatibility-frozen shape — its nodes, per-node status and total world_size are GET /runs/\{run_id\}/topology.

Operation ID: getRun · Service: gateway-api

Authentication

• apiKey (http (bearer)) — Project API key (003 §2): tsk_live_… or tsk_test_… in Authorization: Bearer. Scoped to exactly one project + environment; scopes are a subset of ingest, read, admin. Keys are stored hashed and shown once at creation.
• consoleSession (http (bearer)) — Console session (003 §2): Identity Platform JWT. Data-plane calls add X-Tessera-Project + X-Tessera-Environment headers, validated against org membership.

Parameters

Name	In	Required	Type	Description
run_id	path	yes	string	Run id (run_ ULID, 002 §1).

Responses

Status	Schema	Description
200	TrainingRun	The training run.
default	ErrorEnvelope	Error response (003 §1). Every non-2xx response uses this envelope; the HTTP status matches error.code. Rate-limited requests get 429 resource_exhausted with retry_after_seconds and a Retry-After header; the X-RateLimit-* headers ride on EVERY response, success or error (003 §1; plan-driven per API key + endpoint class — WP-B2). A 503 unavailable carries retry_after_seconds too for a lock-wait timeout (SQLSTATE 55P03), a rule preview at capacity (preview_capacity_exhausted), or a label preview during which the erasure of every entity holding its censor clock began (label_preview_clock_entity_erased): how long to wait before retrying.

GET /runs/{run_id}/annotations

Get a training run's annotations

The run's human display name and tags (TES-034). A run that was never annotated returns revision 0 with a null name and no tags. Another tenant's run id is indistinguishable from a missing one (404 not_found, 003 §3).

Operation ID: getRunAnnotations · Service: gateway-api

Authentication

• apiKey (http (bearer)) — Project API key (003 §2): tsk_live_… or tsk_test_… in Authorization: Bearer. Scoped to exactly one project + environment; scopes are a subset of ingest, read, admin. Keys are stored hashed and shown once at creation.
• consoleSession (http (bearer)) — Console session (003 §2): Identity Platform JWT. Data-plane calls add X-Tessera-Project + X-Tessera-Environment headers, validated against org membership.

Parameters

Name	In	Required	Type	Description
run_id	path	yes	string	Run id (run_ ULID, 002 §1).

Responses

Status	Schema	Description
200	ExperimentAnnotations	The run's annotations.
default	ErrorEnvelope	Error response (003 §1). Every non-2xx response uses this envelope; the HTTP status matches error.code. Rate-limited requests get 429 resource_exhausted with retry_after_seconds and a Retry-After header; the X-RateLimit-* headers ride on EVERY response, success or error (003 §1; plan-driven per API key + endpoint class — WP-B2). A 503 unavailable carries retry_after_seconds too for a lock-wait timeout (SQLSTATE 55P03), a rule preview at capacity (preview_capacity_exhausted), or a label preview during which the erasure of every entity holding its censor clock began (label_preview_clock_entity_erased): how long to wait before retrying.

PATCH /runs/{run_id}/annotations

Update a training run's annotations

Sets or clears the run's display name and replaces its tag set (TES-034). Absent fields are unchanged. Annotations are stored apart from the run: its config, fingerprints, deduplication, lifecycle updated_at and creation provenance stay byte-identical. A request that changes nothing returns the current annotations without a new revision or audit event; an effective change increments revision by one and records one run.annotate audit event in the same transaction. expected_revision makes the update conditional (400 failed_precondition, reason annotation_revision_mismatch, when another change won).

Operation ID: updateRunAnnotations · Service: gateway-api

Authentication

• apiKey (http (bearer)) — Project API key (003 §2): tsk_live_… or tsk_test_… in Authorization: Bearer. Scoped to exactly one project + environment; scopes are a subset of ingest, read, admin. Keys are stored hashed and shown once at creation.
• consoleSession (http (bearer)) — Console session (003 §2): Identity Platform JWT. Data-plane calls add X-Tessera-Project + X-Tessera-Environment headers, validated against org membership.

Parameters

Name	In	Required	Type	Description
run_id	path	yes	string	Run id (run_ ULID, 002 §1).

Request body

ExperimentAnnotationsUpdate

Responses

Status	Schema	Description
200	ExperimentAnnotations	The resulting annotations.
default	ErrorEnvelope	Error response (003 §1). Every non-2xx response uses this envelope; the HTTP status matches error.code. Rate-limited requests get 429 resource_exhausted with retry_after_seconds and a Retry-After header; the X-RateLimit-* headers ride on EVERY response, success or error (003 §1; plan-driven per API key + endpoint class — WP-B2). A 503 unavailable carries retry_after_seconds too for a lock-wait timeout (SQLSTATE 55P03), a rule preview at capacity (preview_capacity_exhausted), or a label preview during which the erasure of every entity holding its censor clock began (label_preview_clock_entity_erased): how long to wait before retrying.

GET /runs/{run_id}/logs

Get training run logs

Trainer log entries, proxied from Cloud Logging filtered by run_id + the resolved project_id (WP-M3 req 10), oldest first (cursor pagination, 003 §1). By default each entry contains only the legacy logged_at, severity, and message fields so existing strict SDK models remain compatible. Pass structured=true to opt into the optional progress, validation, checkpoint, and early-stopping fields.

Operation ID: getRunLogs · Service: gateway-api

Authentication

• apiKey (http (bearer)) — Project API key (003 §2): tsk_live_… or tsk_test_… in Authorization: Bearer. Scoped to exactly one project + environment; scopes are a subset of ingest, read, admin. Keys are stored hashed and shown once at creation.
• consoleSession (http (bearer)) — Console session (003 §2): Identity Platform JWT. Data-plane calls add X-Tessera-Project + X-Tessera-Environment headers, validated against org membership.

Parameters

Name	In	Required	Type	Description
run_id	path	yes	string	Run id (run_ ULID, 002 §1).
cursor	query	no	string	Opaque pagination cursor from a previous response's next_cursor.
limit	query	no	integer	Page size (cursor pagination, 003 §1). Maximum 200.
structured	query	no	boolean	Include optional structured trainer context on each log entry. Omitted or false returns only the three legacy required fields.

Pagination

Cursor pagination (003 §1): pass limit (max 200) and cursor; the response is the pagination envelope — data plus next_cursor (null on the last page).

Responses

Status	Schema	Description
200	RunLogsPage	Page of log entries, oldest first.
default	ErrorEnvelope	Error response (003 §1). Every non-2xx response uses this envelope; the HTTP status matches error.code. Rate-limited requests get 429 resource_exhausted with retry_after_seconds and a Retry-After header; the X-RateLimit-* headers ride on EVERY response, success or error (003 §1; plan-driven per API key + endpoint class — WP-B2). A 503 unavailable carries retry_after_seconds too for a lock-wait timeout (SQLSTATE 55P03), a rule preview at capacity (preview_capacity_exhausted), or a label preview during which the erasure of every entity holding its censor clock began (label_preview_clock_entity_erased): how long to wait before retrying.

GET /runs/{run_id}/metrics

Get training run metrics

Multi-series step-indexed time series from run_metrics (WP-M3 req 10): \{series: \{\<metric_name\>: [[step, value], …]\}, cursor\} where cursor is the highest step included (after_step when nothing new; 0 on a fresh run). ?after_step=\<cursor\> returns only points with step > after_step — the incremental fetch live charts poll (WP-U4); series present on the run but with nothing new come back as empty arrays.

Operation ID: getRunMetrics · Service: gateway-api

Authentication

• apiKey (http (bearer)) — Project API key (003 §2): tsk_live_… or tsk_test_… in Authorization: Bearer. Scoped to exactly one project + environment; scopes are a subset of ingest, read, admin. Keys are stored hashed and shown once at creation.
• consoleSession (http (bearer)) — Console session (003 §2): Identity Platform JWT. Data-plane calls add X-Tessera-Project + X-Tessera-Environment headers, validated against org membership.

Parameters

Name	In	Required	Type	Description
run_id	path	yes	string	Run id (run_ ULID, 002 §1).
after_step	query	no	integer	Return only points with step strictly greater than this cursor.
metric	query	no	string	Comma-separated metric names filtering the series map (e.g. val_loss,lr); omitted → every series.

Responses

Status	Schema	Description
200	RunMetrics	Metric series (optionally incremental / filtered).
default	ErrorEnvelope	Error response (003 §1). Every non-2xx response uses this envelope; the HTTP status matches error.code. Rate-limited requests get 429 resource_exhausted with retry_after_seconds and a Retry-After header; the X-RateLimit-* headers ride on EVERY response, success or error (003 §1; plan-driven per API key + endpoint class — WP-B2). A 503 unavailable carries retry_after_seconds too for a lock-wait timeout (SQLSTATE 55P03), a rule preview at capacity (preview_capacity_exhausted), or a label preview during which the erasure of every entity holding its censor clock began (label_preview_clock_entity_erased): how long to wait before retrying.

GET /runs/{run_id}/recipe

Get a training run's reusable recipe

The exact retained configuration of one run for cloning (TES-034), re-expressed from the run's stored fingerprinted run config (never from the abbreviated TrainingRun echo), plus whether its dataset and label definitions are still current. Read-only: nothing is created or launched. Another tenant's run id is indistinguishable from a missing one (404 not_found, 003 §3). A multi-node run (WP-M6) has no v1 recipe — its closed request shape cannot carry nodes — and is refused with 400 failed_precondition; its replay body is request of GET /runs/\{run_id\}/topology.

Operation ID: getRunRecipe · Service: gateway-api

Authentication

• apiKey (http (bearer)) — Project API key (003 §2): tsk_live_… or tsk_test_… in Authorization: Bearer. Scoped to exactly one project + environment; scopes are a subset of ingest, read, admin. Keys are stored hashed and shown once at creation.
• consoleSession (http (bearer)) — Console session (003 §2): Identity Platform JWT. Data-plane calls add X-Tessera-Project + X-Tessera-Environment headers, validated against org membership.

Parameters

Name	In	Required	Type	Description
run_id	path	yes	string	Run id (run_ ULID, 002 §1).

Responses

Status	Schema	Description
200	TrainingRunRecipe	The run's recipe.
default	ErrorEnvelope	Error response (003 §1). Every non-2xx response uses this envelope; the HTTP status matches error.code. Rate-limited requests get 429 resource_exhausted with retry_after_seconds and a Retry-After header; the X-RateLimit-* headers ride on EVERY response, success or error (003 §1; plan-driven per API key + endpoint class — WP-B2). A 503 unavailable carries retry_after_seconds too for a lock-wait timeout (SQLSTATE 55P03), a rule preview at capacity (preview_capacity_exhausted), or a label preview during which the erasure of every entity holding its censor clock began (label_preview_clock_entity_erased): how long to wait before retrying.

GET /runs/{run_id}/topology

Get a training run's topology

The nodes, total world_size, per-node status and replay body of one run (WP-M6). The closed v1 TrainingRun is compatibility-frozen for installed SDKs and cannot carry this vocabulary, so a multi-node run reports at most its ranks per node in trainer.world_size there and is hidden from the default GET /runs page; everything multi-node is read here. request re-creates the run's stored configuration through POST /runs (a multi-node run's GET /runs/\{run_id\}/recipe is refused with a pointer here). Another tenant's run id is indistinguishable from a missing one (404 not_found, 003 §3).

Operation ID: getRunTopology · Service: gateway-api

Authentication

• apiKey (http (bearer)) — Project API key (003 §2): tsk_live_… or tsk_test_… in Authorization: Bearer. Scoped to exactly one project + environment; scopes are a subset of ingest, read, admin. Keys are stored hashed and shown once at creation.
• consoleSession (http (bearer)) — Console session (003 §2): Identity Platform JWT. Data-plane calls add X-Tessera-Project + X-Tessera-Environment headers, validated against org membership.

Parameters

Name	In	Required	Type	Description
run_id	path	yes	string	Run id (run_ ULID, 002 §1).

Responses

Status	Schema	Description
200	TrainingRunTopology	The run's topology.
default	ErrorEnvelope	Error response (003 §1). Every non-2xx response uses this envelope; the HTTP status matches error.code. Rate-limited requests get 429 resource_exhausted with retry_after_seconds and a Retry-After header; the X-RateLimit-* headers ride on EVERY response, success or error (003 §1; plan-driven per API key + endpoint class — WP-B2). A 503 unavailable carries retry_after_seconds too for a lock-wait timeout (SQLSTATE 55P03), a rule preview at capacity (preview_capacity_exhausted), or a label preview during which the erasure of every entity holding its censor clock began (label_preview_clock_entity_erased): how long to wait before retrying.

POST /runs/{run_id}:cancel

Cancel a training run

Requests cancellation (003 §1 :action): a queued run flips to cancelled immediately; a running run gets a cancel marker the trainer polls every checkpoint interval — it stops gracefully, writes a final checkpoint and flips the run to cancelled (WP-M3 AC9). The Kueue Job is torn down either way. Cancelling a run that is already terminal → 400 failed_precondition.

Operation ID: cancelRun · Service: gateway-api

Authentication

• apiKey (http (bearer)) — Project API key (003 §2): tsk_live_… or tsk_test_… in Authorization: Bearer. Scoped to exactly one project + environment; scopes are a subset of ingest, read, admin. Keys are stored hashed and shown once at creation.
• consoleSession (http (bearer)) — Console session (003 §2): Identity Platform JWT. Data-plane calls add X-Tessera-Project + X-Tessera-Environment headers, validated against org membership.

Parameters

Name	In	Required	Type	Description
Idempotency-Key	header	no	string	Idempotency key accepted by all POSTs (003 §1): 24 h dedup window, keyed per project. POSTs that are reads (batchSlotScores, scoreSlotEvent, deriveSlotBands, validateSourceRawPreset, sampleSource, watchEventFeedHeads and the preview operations: previewSourceMapping, previewCatalogMapping, previewLabel, previewPatternLabel, previewMarker, previewDatasetEligibility, previewSlotAudience, previewSharedCheckpointImport, previewSlotAtlasInquiry) accept the key but never replay a stored response: a retry with the same key is executed again (and metered again) against current data. A stored response that names an entity is removed when that entity is erased. A key that already answered answers only a retry of the request that stored its response: the same caller, environment, operation, path, query, scoping headers and body (a JSON body by its content, a gzip body by its inflated content). The same key with any other request is 409 already_exists with details[0].reason idempotency_key_reused, and that request is not run. The window holds no in-flight marker: two first requests sent at once can both run. A response stored by a release before this rule cannot be matched to its request and is refused the same way until it expires; send the request again with a new key. A body over 8 MiB (ingest: over its 5 MiB request limit) is run and its response is not stored. The ingest batch (POST /events) is the exception, except for an application's credentials: under a key that answered another batch it runs again, uncached, and its events' ids deduplicate them; so it does when its stored response cannot be checked. The operations that return a one-time secret store their response sealed: the stored copy opens only for the same key and credential, and one that cannot be opened is 409 idempotency_key_reused. While the server cannot check a stored response (it cannot read the key that checks it, for one), the request is 503 unavailable with Retry-After: retry with the same key. An operation whose handler claims the key itself answers the same 503, before it runs, while the key-hash pepper cannot be read; any other request sent with a key runs meanwhile, and its response is not stored.
run_id	path	yes	string	Run id (run_ ULID, 002 §1).

Idempotency

This operation accepts an Idempotency-Key header (003 §1): within 24 hours, keyed per project and caller, a retry of the same request gets the first response, and the same key with another request is 409 already_exists (idempotency_key_reused). See the Idempotency-Key parameter for the exceptions.

Responses

Status	Schema	Description
200	TrainingRun	The run after the cancellation request.
default	ErrorEnvelope	Error response (003 §1). Every non-2xx response uses this envelope; the HTTP status matches error.code. Rate-limited requests get 429 resource_exhausted with retry_after_seconds and a Retry-After header; the X-RateLimit-* headers ride on EVERY response, success or error (003 §1; plan-driven per API key + endpoint class — WP-B2). A 503 unavailable carries retry_after_seconds too for a lock-wait timeout (SQLSTATE 55P03), a rule preview at capacity (preview_capacity_exhausted), or a label preview during which the erasure of every entity holding its censor clock began (label_preview_clock_entity_erased): how long to wait before retrying.

Errors

Every non-2xx response uses the 003 §1 error envelope; error.request_id matches the X-Request-Id response header, and the HTTP status always matches error.code:

{
  "error": {
    "code": "invalid_argument",
    "details": [
      {
        "type": "field_violation"
      }
    ],
    "message": "human-readable",
    "request_id": "req_01hxample"
  }
}

Closed error-code set (003 §1): invalid_argument, unauthenticated, permission_denied, not_found, already_exists, failed_precondition, resource_exhausted, internal, unavailable.

resource_exhausted responses (HTTP 429) additionally carry retry_after_seconds. See ErrorEnvelope.