> ## 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: ObserveIdentifier description: Identifier search over submitted identifiers 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: ObserveFinding description: Curated findings that explain errors, their impact and who has to act. x-group: Error management - name: ObserveAlert description: Authentication alert rules, instances and history. x-group: Alert management - name: ObserveAnnotation description: >- Annotations, the project's memory (what is true about the data and how to read it) 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: ObserveProbe description: Raw probe capture items (internal autocapture diagnostics) - name: ObserveTelemetry description: Raw SDK/integration diagnostic telemetry - 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..20, t1..t10. `time` and `value` cannot be excluded. maxItems: 34 items: type: string example: - t2 - osVersion x-oapi-codegen-extra-tags: validate: >- omitempty,max=34,unique,dive,oneof=applicationId browser os osVersion customTag1 customTag2 customTag3 customTag4 customTag5 customTag6 customTag7 customTag8 customTag9 customTag10 customTag11 customTag12 customTag13 customTag14 customTag15 customTag16 customTag17 customTag18 customTag19 customTag20 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..20) 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. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.