> ## 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. # Get time series data > Retrieves time series data for a project (grouped by time) Required API key permission: `observe:timeSeries:read`. ## OpenAPI ````yaml /api-reference/openapi/observe.yaml get /observe/timeSeries 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: get: tags: - ObserveTimeSeries summary: Get time series data description: |- Retrieves time series data for a project (grouped by time) Required API key permission: `observe:timeSeries:read`. operationId: ObserveTimeSeriesGet parameters: - name: fromDate in: query required: true description: >- Range start as a local datetime without timezone, formatted as YYYY-MM-DDTHH:MM:SS (e.g. "2026-05-20T00:00:00"). schema: type: string 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 - name: toDate in: query required: true description: >- Range end as a local datetime without timezone, formatted as YYYY-MM-DDTHH:MM:SS (e.g. "2026-05-20T00:00:00"). schema: type: string 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 - name: interval in: query required: true description: > Aggregation interval. hourly, daily and monthly read the precalculated data. 1m and 5m are dynamic intervals: they are never stored, so the definition's query is run live over the whole range (at most 8 hours, buckets aligned to UTC) and every bucket is flagged live. Dynamic intervals cannot be combined with experimentRunID or flowListID. schema: $ref: '#/components/schemas/observeTimeSeriesReadInterval' x-oapi-codegen-extra-tags: validate: required,oneof=hourly daily monthly 1m 5m - name: name in: query required: true description: Time series name schema: type: string x-oapi-codegen-extra-tags: validate: required - name: groupBy in: query required: false description: > Comma-separated dimension keys to keep; collapsed dimensions are summed. Allowed: applicationId, browser, os, osVersion, customTag1..6, t1..t10. Omitted keeps full detail. schema: type: string example: t2,applicationId x-oapi-codegen-extra-tags: validate: omitempty - name: engagement in: query required: false description: > Flow-series filter: engaged keeps rows whose flow reached a subflow or nested flow, or resolved a decision; non-engaged keeps the rest, i.e. flows that were only routed and abandoned. Only valid for login, signup, enrollment, and recovery flow series. Defaults to all. schema: type: string enum: - all - engaged - non-engaged example: engaged x-oapi-codegen-extra-tags: validate: omitempty,oneof=all engaged non-engaged - name: experimentRunID in: query required: false description: >- Optional experiment run ID (format `exr-`). When set (and the run evaluates this series), each returned series is partitioned by the run's variants: every series carries an extra "variant" dimension (the variant ID, or "-" for the unexposed remainder), so summing across "variant" reproduces the unscoped series. When empty, the response is unchanged. schema: type: string example: exr-123456 x-oapi-codegen-extra-tags: validate: omitempty - name: experimentExposure in: query required: false description: > Experiment exposure scope. "exposed" returns only the share of each series attributed to one of the run's variants: no "-" remainder is synthesized, and flows never assigned to the experiment are excluded entirely. Requires experimentRunID naming a run that evaluates this series. Defaults to all (remainder included). schema: type: string enum: - all - exposed example: exposed x-oapi-codegen-extra-tags: validate: omitempty,oneof=all exposed - name: flowListID in: query required: false description: >- Renders the series over an explicit cohort of flows instead of the precalculated data (format `idl-`, from POST /observe/idLists). The definition's own query is run on demand, scoped to those flow ids and with NO time predicate — the list is the selection, whenever those flows happened — so fromDate/toDate only set the (single) bucket the result is stamped with. The panel is otherwise identical in shape, including groupBy, facets and engagement filtering. Requires a flow-id capable definition (currently the flow series: login-flow-v1, signup-flow-v1, security-enrollment-flow-v1, recovery-flow-v1, custom-flow-v1); other definitions return a validation error. Cannot be combined with experimentRunID. The definition's own scoping still applies, so a list mixing flow types renders only the flows this series is about. schema: type: string example: idl-123456 x-oapi-codegen-extra-tags: validate: omitempty,id=idl - name: live in: query required: false description: > Live recalculation of precalculated data. latest runs the definition's query live for the currently open bucket (the one containing now) instead of reading its stored, possibly stale snapshot; closed buckets keep reading the stored data. Has no effect when the range does not contain the open bucket. Only valid with the hourly interval and cannot be combined with experimentRunID or flowListID. schema: $ref: '#/components/schemas/observeTimeSeriesLiveMode' x-oapi-codegen-extra-tags: validate: omitempty,oneof=latest responses: '200': description: Time series data grouped by time content: application/json: schema: $ref: '#/components/schemas/observeTimeSeriesGetRsp' '429': description: Live read capacity is busy, retry later default: $ref: '#/components/responses/error' security: - bearerAuth: - observe:timeSeries:read components: schemas: observeTimeSeriesReadInterval: type: string enum: - hourly - daily - monthly - 1m - 5m description: > Interval of a time series read: the precalculated intervals plus the dynamic intervals (1m, 5m) that are always computed live observeTimeSeriesLiveMode: type: string enum: - latest description: >- Which buckets of a precalculated read are computed live instead of read from storage observeTimeSeriesGetRsp: type: object required: - panel properties: panel: $ref: '#/components/schemas/observeTimeSeriesPanel' observeTimeSeriesPanel: type: object required: - times - namedTimeSeries - customTags properties: times: type: array items: type: integer format: int64 live: type: array description: > Aligned with times: true when the bucket was computed live from the source tables instead of read from the precalculated data. Omitted when no bucket is live. items: type: boolean namedTimeSeries: type: array items: $ref: '#/components/schemas/observeNamedTimeSeries' customTags: type: array description: >- Ordered custom tag names configured on the project assignment (maps to customTag1..6 dimensions) items: type: string facets: type: object description: > Distinct values per filterable dimension over the unprojected window. Flow series omit t2 because it is the long path. additionalProperties: type: array items: type: string 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 observeNamedTimeSeries: type: object required: - name - dimensions - values properties: name: type: string dimensions: type: object additionalProperties: type: string values: type: array items: type: number format: float 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. ````