Skip to main content

training_studies

GET /training-studies​

List training studies

Training studies of the resolved project + environment, newest first (cursor pagination, 003 §1). The optional status and dataset_id filters combine with AND and apply before the page-size limit; restart pagination when filters change.

Operation ID: listTrainingStudies · 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​

NameInRequiredTypeDescription
cursorquerynostringOpaque pagination cursor from a previous response's next_cursor.
dataset_idquerynostringExact dataset ID recorded on the study. A missing or out-of-scope ID produces an empty page, never a cross-project or cross-environment lookup.
limitquerynointegerPage size (cursor pagination, 003 §1). Maximum 200.
statusquerynostringExact training study status; applied before cursor pagination.

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​

StatusSchemaDescription
200TrainingStudyPagePage of training studies, newest first.
defaultErrorEnvelopeError 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 /training-studies​

Start a training study

Admits a study over a dataset build and a search space (WP-M27 req 5) and answers 202 with the admitted study: queued only while no child could launch yet, otherwise running or later (a superseding study whose children are all reused can already be evaluating or completed). Admission: the dataset build must exist in the project (else 404 not_found), be succeeded with no error-severity entry in its violation report (warn-level entries are findings, never a refusal: the study returns them, up to 50, in dataset_findings with the exact dataset_findings_count, and the training_study.create audit records the same, as createRun records them in run.create) and hold the requested labels (else 400 failed_precondition or invalid_argument, the createRun checks); its manifest must record the longest train row (token_stats.split_max_row_tokens), else 400 failed_precondition with details[0].reason = dataset_rebuild_required (rebuild the dataset); the resolved labels must not be empty (else 400 failed_precondition with details[0].reason = study_requires_labels); search_space must name a published space (default tier_s_cpu_v1) and compute_class a class of its compute family (else 400 invalid_argument); and the deterministic cost estimate, the sum over the children of epochs × train_tokens / (nominal_tokens_per_second_per_node × 3600), must not exceed max_node_hours when the caller set it (the caller's own guard; else 400 failed_precondition with details[0].reason = study_budget_exceeded and the estimated_node_hours and max_node_hours); with max_node_hours omitted any estimate up to the space's ceiling is admitted and recorded in budget (max_node_hours_source: ceiling), and an estimate above the ceiling, which protects shared capacity, is 400 failed_precondition with the same reason study_budget_exceeded and the estimated_node_hours and ceiling. The study is content-addressed on the dataset fingerprint, the search space fingerprint, the resolved labels, the seed and the resolved compute class: an identical request returns the existing study while it is queued, running or evaluating with no cancel in progress, or completed; a failed or cancelled one, or one whose cancel is in progress, is superseded by a new study that reuses its completed children. baseline_fallback and max_node_hours are not part of the identity: a repeat request is admitted again (its own max_node_hours budget check included) before the content address is looked up and, if admitted, returns the existing live study with its stored values. Children launch in grid order as the plan's concurrent_training_runs allows; a plan-limit refusal makes the study wait, never fail. fallback.mode is fixed here: baseline_candidate when baseline_fallback is true (the default) and the entity baseline family is deployed, else keep_incumbent.

Operation ID: createTrainingStudy · 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​

NameInRequiredTypeDescription
Idempotency-KeyheadernostringIdempotency 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​

CreateTrainingStudyRequest

Responses​

StatusSchemaDescription
202TrainingStudyThe training study (new or idempotent existing).
defaultErrorEnvelopeError 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 /training-studies/{study_id}​

Get a training study

One training study with its children (axes, status, the validation value at the shipped step, reused, archived), the winner, the winner's evaluation and verdict, the outcome and fallback (WP-M27 reqs 8–10). Another tenant's study id is indistinguishable from a missing one (404 not_found, 003 §3).

Operation ID: getTrainingStudy · 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​

NameInRequiredTypeDescription
study_idpathyesstringTraining study id (stu_ ULID, 002 §1; WP-M27).

Responses​

StatusSchemaDescription
200TrainingStudyThe training study.
defaultErrorEnvelopeError 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 /training-studies/{study_id}:cancel​

Cancel a training study

An unresolved study (queued, running or evaluating) cancels the queued and running children it launched with cancelRun semantics (reused runs are untouched), is marked cancelled (terminal) and archives nothing: its created models stay unarchived for a superseding study, which archives the ones that lose when it completes (WP-M27 req 12, ERRATA 2026-10-15). A completed study whose fallback.state is pending, training or evaluating has its baseline candidate cancelled (fallback.state becomes cancelled) and keeps its status and outcome. Any other terminal study → 400 failed_precondition.

Operation ID: cancelTrainingStudy · 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​

NameInRequiredTypeDescription
Idempotency-KeyheadernostringIdempotency 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.
study_idpathyesstringTraining study id (stu_ ULID, 002 §1; WP-M27).

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​

StatusSchemaDescription
200TrainingStudyThe study after the cancellation.
defaultErrorEnvelopeError 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.