> ## Documentation Index > Fetch the complete documentation index at: https://docs.corbado.com/llms.txt > Use this file to discover all available pages before exploring further. # Export time series to downloadable files > Exports one or more precalculated time series as CSV or Parquet, one file per series, using a shared date range and interval. Each row represents a non-zero time-bucket and dimension combination, with `time`, `timeLocal`, retained dimensions in canonical order and `value`. `time` is the UTC bucket start (RFC 3339 in CSV, timestamp in Parquet); `timeLocal` uses the project timezone reported in `timeZone`. Dimensions in `excludeColumns` are collapsed and their values summed, as when omitted from `groupBy`. Generation runs while the request remains open. The response streams progress as `application/x-ndjson`; the final event is `completed` with the export descriptor or `failed`. Retrieve files using the [download-link endpoint](/api-reference/observe/time-series-export-download) before `expiresAtMs`. Validation errors return a regular JSON error before streaming starts. Exceeding the project's concurrent-export limit or daily quota returns HTTP 429. Required API key permission: `observe:timeSeries:read`. ## OpenAPI ````yaml /api-reference/openapi/observe.yaml post /observe/timeSeries/export openapi: 3.1.1 info: version: 1.0.0 title: Corbado API description: > # Introduction This documentation gives an overview of all Corbado API calls to implement authentication observe. contact: name: Corbado team email: support@corbado.com url: https://www.corbado.com servers: - url: https://api.cloud.corbado.io/v1 security: - bearerAuth: [] tags: - name: ObserveFlow description: Flow search and related APIs x-group: Journeys and users - name: ObserveSubFlow description: Subflow search and related APIs x-group: Journeys and users - name: ObserveUser description: User search and related APIs x-group: Journeys and users - name: ObserveClientEnv description: Client environment search APIs x-group: Journeys and users - name: ObserveTimeSeries description: Time series query APIs x-group: Metrics and funnels - name: ObserveFunnel description: Historical funnel metrics, dictionaries and coverage. x-group: Metrics and funnels - name: ObserveEvent description: Event ingestion and event feed APIs x-group: Events - name: ObserveError description: Named authentication errors and recommendations. x-group: Error management - name: ObserveErrorFlavour description: Error variants and their impact on authentication outcomes. x-group: Error management - name: ObserveAlert description: Authentication alert rules, instances and history. x-group: Alert management - name: ObserveAnnotation description: Annotation APIs (dated notes for analytics context) x-group: Annotations - name: ObserveTableExport description: Table export file listing and download APIs x-group: Data exports - name: ObserveTimeSeriesExport description: Time-series export generation and downloads. x-group: Data exports - name: ObserveDataExport description: Data export APIs x-group: User data - name: ObserveDataDeletionJob description: Data deletion job APIs x-group: User data - name: ObserveFlowTypeDefinition description: Flow type definitions used in authentication journeys. x-group: Catalogs and labels - name: ObserveCatalog description: Catalog APIs x-group: Catalogs and labels - name: OpenAPI description: Downloadable API specification - name: ProjectOperationExecution description: Project-scoped operation history and pipeline health - name: ObserveClassification description: Flow and subflow classification APIs - name: ObserveIntegrationStats description: Integration stats APIs - name: ObserveTimeSeriesPrecalculation description: Time series precalculation APIs - name: ObserveIDList x-group: Saved ID lists description: Stored ID-list selection APIs - name: ObserveDataContext description: Schema-loose data context APIs for agent and debugging tooling - name: ObserveData description: Observe data administration APIs - name: ObserveTrackingStats description: Tracking ingestion stats APIs - name: ObserveExperiment x-group: Experiments description: Experiment catalog and run APIs - name: ObserveDataPolicy description: >- Project data policy catalogue (retention selected by the SDK's meta.dataPolicy code) - name: ObserveMetadata x-group: Metadata description: Authenticator metadata APIs (FIDO MDS + passkey AAGUID) - name: ObservePasskey x-group: Passkey analysis description: Observed passkey search and cohort analysis. paths: /observe/timeSeries/export: post: tags: - ObserveTimeSeriesExport summary: Export time series to downloadable files description: >- Exports one or more precalculated time series as CSV or Parquet, one file per series, using a shared date range and interval. Each row represents a non-zero time-bucket and dimension combination, with `time`, `timeLocal`, retained dimensions in canonical order and `value`. `time` is the UTC bucket start (RFC 3339 in CSV, timestamp in Parquet); `timeLocal` uses the project timezone reported in `timeZone`. Dimensions in `excludeColumns` are collapsed and their values summed, as when omitted from `groupBy`. Generation runs while the request remains open. The response streams progress as `application/x-ndjson`; the final event is `completed` with the export descriptor or `failed`. Retrieve files using the [download-link endpoint](/api-reference/observe/time-series-export-download) before `expiresAtMs`. Validation errors return a regular JSON error before streaming starts. Exceeding the project's concurrent-export limit or daily quota returns HTTP 429. Required API key permission: `observe:timeSeries:read`. operationId: ObserveTimeSeriesExport requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/observeTimeSeriesExportReq' responses: '200': description: >- Newline-delimited JSON progress stream; the final line carries the export descriptor. content: application/x-ndjson: schema: $ref: '#/components/schemas/observeTimeSeriesExportEvent' default: $ref: '#/components/responses/error' security: - bearerAuth: - observe:timeSeries:read components: schemas: observeTimeSeriesExportReq: type: object required: - fromDate - toDate - interval - format - timeSeries properties: fromDate: type: string description: >- Range start in UTC, formatted as YYYY-MM-DDTHH:MM:SS without a timezone suffix. Convert project-local selections to UTC before calling. Applies to every exported time series. pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}$ example: '2026-05-20T00:00:00' x-oapi-codegen-extra-tags: validate: required,datetime=2006-01-02T15:04:05 toDate: type: string description: >- Exclusive range end in UTC, formatted as YYYY-MM-DDTHH:MM:SS without a timezone suffix. Must be after fromDate; the maximum range depends on the interval. pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}$ example: '2026-06-20T00:00:00' x-oapi-codegen-extra-tags: validate: required,datetime=2006-01-02T15:04:05 interval: type: string description: >- Aggregation interval, applies to every exported time series. One of: hourly, daily, monthly. example: daily x-oapi-codegen-extra-tags: validate: required,oneof=hourly daily monthly format: type: string description: >- File format, applies to every exported time series. One of: csv, parquet. example: csv x-oapi-codegen-extra-tags: validate: required,oneof=csv parquet timeSeries: type: array description: >- Time series to export, one file each. Names must be unique within the request. minItems: 1 maxItems: 20 items: $ref: '#/components/schemas/observeTimeSeriesExportSeriesReq' x-oapi-codegen-extra-tags: validate: required,min=1,max=20,dive observeTimeSeriesExportEvent: type: object description: One line of the export progress stream. required: - type - exportID properties: type: type: string enum: - started - progress - completed - failed exportID: type: string series: type: string description: Time series name the progress event refers to sliceFrom: type: string description: Start of the time slice just written (progress) sliceTo: type: string description: Exclusive end of the time slice just written (progress) rows: type: integer format: int64 description: Rows written for this series so far (progress) bytes: type: integer format: int64 description: Bytes written for this series so far (progress) export: $ref: '#/components/schemas/observeTimeSeriesExport' observeTimeSeriesExportSeriesReq: type: object required: - name properties: name: type: string description: >- Time series definition name (see GET /observe/timeSeriesDefinitions), e.g. login-flow-v1 example: login-flow-v1 x-oapi-codegen-extra-tags: validate: required,min=1,max=100 excludeColumns: type: array description: > Dimension columns to leave out of the file. Excluding a dimension collapses it: rows that differ only in excluded dimensions are summed (same semantics as omitting the key from groupBy). Allowed: applicationId, browser, os, osVersion, customTag1..6, t1..t10. `time` and `value` cannot be excluded. maxItems: 22 items: type: string example: - t2 - osVersion x-oapi-codegen-extra-tags: validate: >- omitempty,max=22,unique,dive,oneof=applicationId browser os osVersion customTag1 customTag2 customTag3 customTag4 customTag5 customTag6 t1 t2 t3 t4 t5 t6 t7 t8 t9 t10 engagement: type: string description: >- Flow-series engagement filter, same semantics as GET /observe/timeSeries. One of: all, engaged, non-engaged. Defaults to all. example: all x-oapi-codegen-extra-tags: validate: omitempty,oneof=all engaged non-engaged observeTimeSeriesExport: type: object required: - exportID - status - createdMs - fromDate - toDate - interval - format - timeZone - timeSeries properties: exportID: type: string description: Export ID (format `tse-`) example: tse-123456 status: $ref: '#/components/schemas/observeTimeSeriesExportStatus' createdMs: $ref: '#/components/schemas/unixMilliTimestamp' completedMs: $ref: '#/components/schemas/unixMilliTimestamp' expiresAtMs: $ref: '#/components/schemas/unixMilliTimestamp' fromDate: type: string description: UTC range start without a timezone suffix. toDate: type: string description: Exclusive UTC range end without a timezone suffix. interval: $ref: '#/components/schemas/observeTimeSeriesInterval' format: $ref: '#/components/schemas/observeTimeSeriesExportFormat' timeZone: type: string description: >- IANA timezone of the project at export time; the files' timeLocal column renders bucket starts in it. example: Europe/Berlin sizeBytes: type: integer format: int64 description: Total size of all files in bytes timeSeries: type: array items: $ref: '#/components/schemas/observeTimeSeriesExportSeries' error: type: string description: Failure reason for failed exports errorRspV2: type: object required: - error properties: error: type: object required: - message properties: message: description: Error message type: string example: Validation failed details: description: Validation error details per field type: array items: type: object required: - field - message properties: field: description: Field name that failed validation type: string example: projectID message: description: Validation error message type: string example: required observeTimeSeriesExportStatus: type: string description: > Lifecycle status of a time series export. `running` while it is generated, `completed` once every file is stored, `failed` when generation was aborted (deadline, error, disconnect), `expired` once the files were removed after the retention period. `pending` is reserved for queued exports. enum: - pending - running - completed - failed - expired unixMilliTimestamp: type: integer format: int64 description: >- Unix timestamp in milliseconds elapsed since January 1, 1970, 00:00:00 UTC example: 1752738240000 observeTimeSeriesInterval: type: string enum: - hourly - daily - monthly description: Aggregation interval for the time series observeTimeSeriesExportFormat: type: string description: File format of a time series export enum: - csv - parquet observeTimeSeriesExportSeries: type: object required: - name - excludeColumns - engagement - columns - customTags properties: name: type: string excludeColumns: type: array items: type: string engagement: type: string columns: type: array description: Column names of the file in order items: type: string customTags: type: object description: >- Configured custom tag name per positional column key (customTag1..6) of this time series, as used in the file additionalProperties: type: string columnGuide: description: >- Column meanings captured when this export was created. Absent on older exports. allOf: - $ref: '#/components/schemas/observeTimeSeriesColumnGuide' file: $ref: '#/components/schemas/observeTimeSeriesExportFile' observeTimeSeriesColumnGuide: type: object description: Column descriptions and interpretation notes for one time series. required: - version - columns - notes properties: version: type: integer description: Version of the column guide format. columns: type: array description: >- Only the exported columns, in file order. In precalculation config, all available export columns. items: $ref: '#/components/schemas/observeTimeSeriesColumn' notes: type: array items: type: string description: >- How to interpret aggregated rows, omitted values and excluded dimensions. observeTimeSeriesExportFile: type: object required: - name - size - checksum - rows properties: name: type: string description: File name within the export, e.g. login-flow-v1.csv size: type: integer format: int64 description: File size in bytes checksum: type: string description: Checksum of the stored object as reported by the object store rows: type: integer format: int64 description: Number of data rows in the file (excluding the CSV header) observeTimeSeriesColumn: type: object description: Meaning of one stable export column for a specific time series. required: - key - label - description - values properties: key: type: string description: Stable column key, matching the exported header. label: type: string description: Human-readable column label. description: type: string description: Explanation of the column meaning for this series. values: type: string description: Value meanings or guidance for open-ended values and missing data. responses: error: description: Error content: application/json: schema: $ref: '#/components/schemas/errorRspV2' securitySchemes: bearerAuth: type: http scheme: bearer description: >- Use an Observe API key from the management console. The key selects the project and must grant the permission listed on the operation. Keep this key on your server. ````