Skip to content

report_export

Report export contract models.

An export renders a study or project report server-side into a deterministic artifact: a branded PDF, a plain-markdown bundle users can annotate offline, or the raw report payload as JSON — the same numbers and figures the live report page shows, for programmatic consumers and for clients that load large reports asynchronously. Exports run asynchronously; clients create one, poll its status, and download the artifact until it expires.

EventsExportParams pydantic-model

Bases: BaseModel

Cohort selection for an events-zip export.

The archive bundles the events file of every completed analysis in the cohort, one file per analysis, each byte-identical to the single analysis download. The cohort is the project, narrowed by whichever selectors are given: study_ids keeps the named studies, analysis_ids keeps the named analyses; both together keep the analyses that satisfy both. Ids outside the project are ignored.

Fields:

analysis_ids = None pydantic-field

Analyses whose events files join the zip; those not completed, or not in the project, are left out. None = no narrowing by analysis.

study_ids = None pydantic-field

Studies whose completed analyses' events files join the zip. None = no narrowing by study.

ReportExportCreate pydantic-model

Bases: BaseModel

Request body for creating a report export.

Fields:

email_copy = False pydantic-field

Also email the artifact link to the requesting user's verified address once the export completes. NOT YET HONORED: the server rejects true until the email delivery path ships.

events_params = None pydantic-field

events-zip exports only: which studies to bundle. Rejected for document formats.

format pydantic-field

Artifact format to render.

layout = None pydantic-field

Section selection/order to apply; omitted = every section in natural order. Snapshotted on the export.

project_params = None pydantic-field

Project exports only: which report mode to render. None = by-group over every tag.

ReportExportListResponse pydantic-model

Bases: PaginatedResponse

A page of the user's report exports, newest first.

Paginated like the other listings: total is the whole collection, not the page, so a client can show how many exports exist and page through them rather than treating one capped read as the whole history.

Fields:

exports pydantic-field

The exports on this page.

ReportExportOut pydantic-model

Bases: BaseModel

One report export and its lifecycle state.

Fields:

appendix_download_url = None pydantic-field

Short-lived download URL for the export's audit-appendix CSV snapshot, for formats that keep the appendix out of the main artifact (PDF). Present only while completed and not expired; None for formats that embed the appendix and for rows predating the field.

completed_at = None pydantic-field

When rendering finished (success or failure).

created_at pydantic-field

When the export was requested.

download_url = None pydantic-field

Short-lived download URL; present only while completed and not expired.

error = None pydantic-field

Failure reason when status is failed.

expires_at = None pydantic-field

When the artifact is deleted; absent until completed.

format pydantic-field

Artifact format.

id pydantic-field

Export identifier.

kind pydantic-field

Study or project report.

owner_id = None pydantic-field

The member who added it. Only they, or the project's owner, may change or remove it; it passes to the project's owner when they leave the organization.

project_id pydantic-field

The project the report belongs to.

project_name = None pydantic-field

Display name of the project at export time. None for rows predating the field.

size_bytes = None pydantic-field

Artifact size once completed.

status pydantic-field

Lifecycle state.

study_id = None pydantic-field

The study, for study-report exports.

study_name = None pydantic-field

Display name of the study at export time, for study-report exports. None otherwise or predating.

ReportExportProjectParams pydantic-model

Bases: BaseModel

Project-report mode selection for an export.

The field NAMES mirror the report GET's query parameters; by_group's DEFAULT does not. Exporting a project report is grouped unless you ask for flat, while reading one is flat unless you ask for grouped. Pass by_group explicitly and the two agree.

Fields:

Validators:

  • _validate_stratification

analysis_configs = None pydantic-field

Only these analysis configurations contribute to the report; None includes every completed analysis. A report over one pipeline is the same report with the others left out — every count, card, figure and table follows the selection.

by_group = True pydantic-field

Group statistics by study tags. Defaults to ON — the opposite of the by_group query parameter on GET /projects/{project}/report, which defaults to OFF. An export that omits this renders by-group over every tag; pass it explicitly rather than relying on either default.

calendar_granularity = 'month' pydantic-field

The span of one bin on a 'calendar' basis; ignored otherwise.

groups = None pydantic-field

Tags forming the comparison groups; None = every tag.

longitudinal = False pydantic-field

Compute the longitudinal section (the flat boxplot with time bins as rows, one chart per metric) alongside the flat aggregates. Documents render it as an "Over time" block: the bins table and one figure per metric.

longitudinal_basis = None pydantic-field

What the bins are; only meaningful with longitudinal. None lets the server choose: 'session-index' when any study in scope carries a subject key, else 'calendar'.

stratify_by = None pydantic-field

Stratify statistics by a subject-metadata factor instead of tags. When set, tag grouping is not applied (by_group is ignored) and groups must be omitted. Studies missing the factor form their own 'Not set' stratum.

stratify_edges = None pydantic-field

Bin edges overriding the server's configured defaults; numeric factors (age, bmi) only. Strictly increasing; bins are half-open intervals [a, b).

subjects = None pydantic-field

Draw these subjects as lines beside the bins, one series each; only meaningful with longitudinal. Keys are compared case- and whitespace-insensitively, as grouping does.

SectionLayoutEntry pydantic-model

Bases: BaseModel

One section of the user-configurable report layout.

Fields:

columns = None pydantic-field

The stored selection for this entry: COLUMN keys for event/project stats tables, ROW (metric) keys for biomarker and biomarker-summary tables (their curated set is rows), and row/series names for chart entries. None = the curated default set. Carried in the layout document, so exports honor the page's selection.

key pydantic-field

The layout document holds two entry kinds. SECTION entries name a key of the report's served sections (the SECTION_KEY_/SECTION_PREFIX_ vocabulary in this module), such as 'statistics-window', 'hypnogram:{analysis_id}', 'event-stats:{analysis_id}', 'family-comparison:{family}' or 'stats-card:{config_id}'. A figure section ('chart:{chart_key}') also carries which of its rows show. PRESENTATION entries carry a selection but name no section: 'chart-groups' (the group-legend series filter). Keys a renderer does not know are ignored; a section the layout does not mention takes its served default visibility.

visible pydantic-field

Whether the section appears in the report.