Skip to content

batch

Shared models for batch endpoints.

Defines request/response models for all batch operations: - Batch study creation - Batch analysis submission - Batch analysis cancellation - Batch event retrieval - Batch analysis status polling - Batch recording details - Batch channel patch

MAX_BATCH_ANALYSIS_IDS = 100 module-attribute

Analysis ids in one batch cancel, status poll, events or blocks read.

MAX_BATCH_ANALYSIS_ITEMS = 500 module-attribute

Analyses (targets × pipeline steps) in one batch submission.

MAX_BATCH_CHANNEL_PATCHES = 200 module-attribute

Patches in one bulk channel patch.

MAX_BATCH_RECORDING_IDS = 100 module-attribute

Recording ids in one batch recording-details read.

MAX_BATCH_STUDY_IDS = 100 module-attribute

Study ids in one batch recordings-by-studies or studies-by-ids read.

MAX_BATCH_STUDY_ITEMS = 500 module-attribute

Studies created, metadata patches or lights assignments in one request.

BatchAnalysesQuote pydantic-model

Bases: BaseModel

Pre-flight cost quote for a batch submission (same body as the submit).

Runs the exact per-step validation/pricing path the submission uses, so a quoted (non-error) step submits at that price. The aggregate mirrors :class:~yousleep_common.models.billing.BillingQuote: each balance the batch uses gets its own line, and blocked_reason applies when any of them cannot cover its part, against the org's current balances. Advisory — the submission's own reserve remains the gate.

Fields:

blocked_reason = None pydantic-field

Why the batch would be rejected (a balance it uses cannot cover its part), or null.

input_coverage pydantic-field

Per step, how many recordings have each declared input.

placement = None pydantic-field

Where the batch's analyses would run. Null from a server that predates it, and when no step was quoted.

studies_without_recordings pydantic-field

Studies the selector addressed that have no recording to analyse; they are not among the results. Empty for explicit targets.

total_estimated_credits pydantic-field

Sum of the quoted steps' credit costs (errored steps excluded).

wallets pydantic-field

What the batch asks of each balance it uses: research analyses of grants, commercial ones of purchased credits.

BatchAnalysisIdsRequest pydantic-model

Bases: BaseModel

Shared base for batch requests that take a list of analysis IDs.

Fields:

  • analysis_ids (list[UUID])

BatchAnalysisPipelineStep pydantic-model

Bases: BaseModel

A single step in a batch analysis pipeline.

Fields:

  • step_id (str | None)
  • analysis_config_id (AnalysisConfigIdStr)
  • default_channels (list[str] | None)
  • parameters (list[tuple[str, str | int | float | bool]])
  • depends_on (list[str])
  • per_recording_overrides (dict[UUID, BatchRecordingOverride] | None)

BatchAnalysisResult pydantic-model

Bases: BaseModel

Result for a single (target, step) pair in a batch analysis response.

Fields:

BatchAnalysisStatusResult pydantic-model

Bases: BaseModel

Result for a single analysis in batch status polling.

Fields:

BatchAnalysisStatusSummary pydantic-model

Bases: _OkErrorSummary

Summary for batch analysis status polling.

Fields:

  • total (int)
  • ok (int)
  • errors (int)

BatchAnalysisSummary pydantic-model

Bases: BatchSummary

Summary for batch analysis submission.

Fields:

  • total (int)
  • submitted (int)
  • errors (int)

BatchAnalysisTarget pydantic-model

Bases: BaseModel

A target recording for batch analysis submission.

Fields:

  • study_id (UUID)
  • recording_id (UUID)

BatchCancelAnalysesRequest pydantic-model

Bases: BatchAnalysisIdsRequest

Request body for batch analysis cancellation.

Fields:

  • analysis_ids (list[UUID])

BatchCancelAnalysesResponse pydantic-model

Bases: BaseModel

Response for batch analysis cancellation.

Fields:

BatchCancelResult pydantic-model

Bases: BaseModel

Result for a single analysis cancellation.

Fields:

  • analysis_id (UUID)
  • status (Literal['cancelled', 'error'])
  • error (BatchItemError | None)

BatchCancelSummary pydantic-model

Bases: BatchSummary

Summary for batch analysis cancellation.

Fields:

  • total (int)
  • cancelled (int)
  • errors (int)

BatchChannelPatchSummary pydantic-model

Bases: BatchSummary

Summary for the bulk channel patch (total = number of patches submitted).

Fields:

  • total (int)
  • updated (int)
  • errors (int)
  • channels_updated (int)

BatchCreateStudiesRequest pydantic-model

Bases: BaseModel

Request body for batch study creation.

Fields:

BatchCreateStudiesResponse pydantic-model

Bases: BaseModel

Response for batch study creation.

Fields:

BatchEventBlocksResult pydantic-model

Bases: BaseModel

Result for a single analysis in batch event-block retrieval.

Fields:

count = None pydantic-field

Events the document decodes to — the sum of every block's slot count.

BatchEventResult pydantic-model

Bases: BaseModel

Result for a single analysis in batch event retrieval.

Fields:

  • analysis_id (UUID)
  • status (Literal['ok', 'error'])
  • events (list[Event] | None)
  • count (int | None)
  • error (BatchItemError | None)

BatchEventSummary pydantic-model

Bases: _OkErrorSummary

Summary for batch event retrieval.

Fields:

  • total (int)
  • ok (int)
  • errors (int)

BatchGetAnalysesStatusRequest pydantic-model

Bases: BatchAnalysisIdsRequest

Request body for batch analysis status polling.

Fields:

  • analysis_ids (list[UUID])

BatchGetAnalysesStatusResponse pydantic-model

Bases: BaseModel

Response for batch analysis status polling.

Fields:

BatchGetEventBlocksRequest pydantic-model

Bases: BatchAnalysisIdsRequest

Request body for batch event-block retrieval.

Deliberately carries no filter. The single-analysis block endpoint has none either — a block document is meant to be fetched once and sliced locally — and giving the batch form a filter the per-analysis form lacks would make the two disagree about what a block document is.

Fields:

analysis_ids pydantic-field

Analyses to fetch blocks for — at most the schema's maxItems per request, which is the cap the server enforces (GET /status/limits reports the same number).

BatchGetEventBlocksResponse pydantic-model

Bases: BaseModel

Response for batch event-block retrieval.

Fields:

BatchGetEventsRequest pydantic-model

Bases: BatchAnalysisIdsRequest

Request body for batch event retrieval.

Fields:

BatchGetEventsResponse pydantic-model

Bases: BaseModel

Response for batch event retrieval.

Fields:

BatchGetRecordingsByStudiesRequest pydantic-model

Bases: BaseModel

Request body for fetching the recordings of multiple studies in one call.

Fields:

  • study_ids (list[UUID])

BatchGetRecordingsByStudiesResponse pydantic-model

Bases: BaseModel

Response for batch recordings-by-study retrieval (keyed by study id).

Fields:

BatchGetRecordingsDetailsRequest pydantic-model

Bases: BaseModel

Request body for batch recording details retrieval.

Fields:

  • recording_ids (list[UUID])

BatchGetRecordingsDetailsResponse pydantic-model

Bases: BaseModel

Response for batch recording details retrieval.

Fields:

BatchGetStudiesByIdsRequest pydantic-model

Bases: BaseModel

Request body for fetching multiple studies by id in one call.

Fields:

  • study_ids (list[UUID])

BatchGetStudiesByIdsResponse pydantic-model

Bases: BaseModel

Response for batch study by-id retrieval (keyed by study id).

Fields:

BatchItemError pydantic-model

Bases: BaseModel

Per-item error in a batch response.

Fields:

code pydantic-field

Stable machine-readable error code for this item; branch on this, not on the message text.

BatchPatchChannelsRequest pydantic-model

Bases: BaseModel

Request body for the bulk channel patch.

Fields:

BatchPatchChannelsResponse pydantic-model

Bases: BaseModel

Response for the bulk channel patch.

Fields:

BatchQuoteResult pydantic-model

Bases: BaseModel

Quoted cost (or error) for a single (target, step) pair.

Fields:

channels = None pydantic-field

The recording's channels this run receives, by name, in the order the analysis gets them: the platform's match (the first ones in montage order where the recording has more than the analysis takes) or the channels chosen explicitly. Null on a refused result.

missing_inputs = None pydantic-field

The declared inputs this recording lacks, by name (a channel type, an exact channel, or a subject value); empty when it has every one. Null when the step was not resolved against the recording.

BatchQuoteSummary pydantic-model

Bases: BatchSummary

Summary for a batch analysis quote.

Fields:

  • total (int)
  • quoted (int)
  • errors (int)

BatchRecordingDetailResult pydantic-model

Bases: BaseModel

Result for a single recording in batch details retrieval.

Fields:

BatchRecordingDetailSummary pydantic-model

Bases: _OkErrorSummary

Summary for batch recording details retrieval.

Fields:

  • total (int)
  • ok (int)
  • errors (int)

BatchRecordingOverride pydantic-model

Bases: BaseModel

Per-recording overrides for a pipeline step.

Fields:

  • channels (list[str] | None)

BatchRecordingsByStudyResult pydantic-model

Bases: BaseModel

Result for a single study in batch recordings-by-study retrieval.

Fields:

BatchRecordingsByStudySummary pydantic-model

Bases: _OkErrorSummary

Summary for batch recordings-by-study retrieval.

Fields:

  • total (int)
  • ok (int)
  • errors (int)

BatchStudyByIdResult pydantic-model

Bases: BaseModel

Result for a single study in batch by-id retrieval.

Fields:

BatchStudyByIdSummary pydantic-model

Bases: _OkErrorSummary

Summary for batch study by-id retrieval.

Fields:

  • total (int)
  • ok (int)
  • errors (int)

BatchStudyItem pydantic-model

Bases: BaseModel

A single study to create in a batch.

Fields:

session_index = None pydantic-field

Declared position of this study in its subject's series, 1 = first. Same contract as StudyMetadata.session_index.

subject_key = None pydantic-field

The person this study belongs to, so a night is filed under its subject at creation rather than patched in afterwards. Same contract as StudyMetadata.subject_key.

BatchStudyResult pydantic-model

Bases: BaseModel

Result for a single study in a batch response.

Fields:

BatchStudySummary pydantic-model

Bases: BatchSummary

Summary for batch study creation.

Fields:

  • total (int)
  • created (int)
  • errors (int)

BatchSubmitAnalysesRequest pydantic-model

Bases: BaseModel

Request body for batch analysis submission (and its quote).

Targets are addressed either explicitly (targets) or through a study selector (the batch addressing language): the server resolves the matched studies to their recordings at acceptance time. Exactly one of the two must be set. Live-set selectors (filter/all) must state expected_count — the matched-STUDY total the caller last resolved (the filtered study list's total); the server re-resolves and rejects on a mismatch. A selector that resolves to more recordings than an explicit request may carry is rejected with the resolved count — narrow the filter and submit in slices.

Fields:

Validators:

  • _one_addressing_mode

complete_inputs_only = False pydantic-field

Leave out recordings that lack an optional input the analysis declares, so every run receives the same inputs. A recording lacking a required input is refused either way.

expected_count = None pydantic-field

Required for filter/all selectors: the matched-study count the caller saw. The server re-resolves and rejects on a mismatch.

selector = None pydantic-field

Address targets as a study set; the server resolves each matched study's recordings.

BatchSubmitAnalysesResponse pydantic-model

Bases: BaseModel

Response for batch analysis submission.

Fields:

studies_without_recordings pydantic-field

Studies the selector addressed that have no recording to analyse; nothing was submitted for them. Empty for explicit targets.

BatchSummary pydantic-model

Bases: BaseModel

Base summary counts for batch responses. Subclassed per-endpoint.

Fields:

  • total (int)

ChannelPatch pydantic-model

Bases: BaseModel

A single bulk channel edit.

Matches every channel named match_name across the project's recordings and applies the provided fields; unset fields are left unchanged. At least one of new_name / type / unit must be set.

Fields:

Validators:

  • _require_a_change

canonical_name = None pydantic-field

The canonical name ('C3-M2', 'E1') of these channels, if setting it; send null to clear. Recorded as set by a person.

laterality = None pydantic-field

The body side these channels record, if setting it; send null to clear. Recorded as set by a person.

match_name pydantic-field

Current channel name to match across recordings.

new_name = None pydantic-field

New channel name (rename), if changing. At most 16 characters, the EDF label length and the limit every channel read enforces — a longer name would be stored and then fail validation on every read of the recording's channels, so it is rejected here.

type = None pydantic-field

New channel type, if changing.

unit = None pydantic-field

New physical unit, if changing.

ChannelPatchResult pydantic-model

Bases: BaseModel

Result for a single channel patch.

Fields:

  • match_name (str)
  • status (Literal['updated', 'error'])
  • channels_updated (int)
  • recordings_affected (int)
  • error (BatchItemError | None)

InputCoverage pydantic-model

Bases: BaseModel

How many of a step's recordings have one input its analysis declares.

Fields:

  • name (str)
  • kind (Literal['channel_type', 'channel', 'subject_value'])
  • required (bool)
  • present (NonNegativeInt)

name pydantic-field

As the configuration declares it: a channel type (EEG), an exact channel (C3-M2), or a subject value (age).

present pydantic-field

Recordings that have it: at least the declared minimum of channels, or a recorded value.

required pydantic-field

Whether a recording without it is refused. An optional input is used when the recording has it.

StepInputCoverage pydantic-model

Bases: BaseModel

What one step's recordings offer of the inputs its analysis declares.

Fields:

complete pydantic-field

Recordings with every declared input, optional ones included.

recordings pydantic-field

Recordings the step was resolved against.