> ## 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. # Search flows by filter criteria > Finds Observe flows that match the provided filters. Provide at least one of the following filters: `userIDs`, `flowIDs`, `sessionIDs`, or a complete `fromDate` / `toDate` range. When provided, the date range may span at most 366 days. Results are ordered as a stable timeline, oldest first (by creation time), and capped at `limit`. Required API key permission: `observe:flow:read`. ## OpenAPI ````yaml /api-reference/openapi/observe.yaml post /observe/flowSearch 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/flowSearch: post: tags: - ObserveFlow summary: Search flows by filter criteria description: >- Finds Observe flows that match the provided filters. Provide at least one of the following filters: `userIDs`, `flowIDs`, `sessionIDs`, or a complete `fromDate` / `toDate` range. When provided, the date range may span at most 366 days. Results are ordered as a stable timeline, oldest first (by creation time), and capped at `limit`. Required API key permission: `observe:flow:read`. operationId: ObserveFlowSearch requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/observeFlowSearchReq' responses: '200': description: Matching flows plus the total match count. content: application/json: schema: $ref: '#/components/schemas/observeFlowSearchRsp' default: $ref: '#/components/responses/error' security: - bearerAuth: - observe:flow:read components: schemas: observeFlowSearchReq: type: object properties: userIDs: type: array description: User IDs to filter flows by (format `tus-`). items: type: string x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=500,dive,id=tus flowIDs: type: array description: Flow IDs to filter by (format `flw-`). items: type: string x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=500,dive,id=flw flowListIDs: type: array description: >- Restrict the search to the flows held by these stored ID lists (format `idl-`, from POST /observe/idLists) — the same cohort handles `GET /observe/timeSeries?flowListID=` renders a funnel over. Several lists are unioned, and the result is intersected with `flowIDs` when both are given. Counts as a selector, so a cohort-scoped search needs no date range; all other filters (path, tags, outcome, …) still narrow within the cohort. items: type: string x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=4,dive,id=idl sessionIDs: type: array description: Public session UUIDs to filter flows by. items: type: string x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=500,dive,uuid fromDate: type: string description: >- Optional start of date range (yyyy-MM-dd or yyyy-MM-ddTHH:mm:ss), interpreted in UTC. Requires `toDate`. x-oapi-codegen-extra-tags: validate: omitempty,min=10,max=19 toDate: type: string description: >- Optional exclusive end of date range (yyyy-MM-dd or yyyy-MM-ddTHH:mm:ss), interpreted in UTC. Requires `fromDate` and must be at most 366 days after it. x-oapi-codegen-extra-tags: validate: omitempty,min=10,max=19 flowType: type: array description: Filter by built-in or project-specific custom flow type names. items: type: string minLength: 1 maxLength: 50 x-oapi-codegen-extra-tags: validate: omitempty,min=1,dive,min=1,max=50 touchpoint: type: array x-go-type: '[]*string' description: >- Filter by touchpoint values; null includes flows with an absent or empty touchpoint. x-oapi-codegen-extra-tags: validate: omitempty,min=1,dive,omitnil,min=1,max=255 items: type: - string - 'null' outcome: type: array description: Filter by outcome values items: type: string enum: - complete - incomplete - skipped - invisible - visible-auto-skip x-oapi-codegen-extra-tags: validate: >- omitempty,min=1,dive,oneof=complete incomplete skipped invisible visible-auto-skip path: type: array description: Filter by long_path values (the t2 dimension of *-flow-v1) items: type: string x-oapi-codegen-extra-tags: validate: omitempty,min=1,dive,min=1,max=3000 osName: type: array x-go-type: '[]*string' description: >- Filter by OS name; null includes flows with an absent or empty OS name. x-oapi-codegen-extra-tags: validate: omitempty,min=1,dive,omitnil,min=1,max=100 items: type: - string - 'null' browserName: type: array x-go-type: '[]*string' description: >- Filter by browser name; null includes flows with an absent or empty browser name. x-oapi-codegen-extra-tags: validate: omitempty,min=1,dive,omitnil,min=1,max=100 items: type: - string - 'null' osVersion: type: array description: >- Filter by OS version (the maj.min.pat string, matching the error-flavour timeseries tag) items: type: string x-oapi-codegen-extra-tags: validate: omitempty,min=1,dive,min=1,max=100 flavourIDs: type: array description: >- Restrict to flows that carry an error occurrence of one of these error flavours (format `erf-`). items: type: string x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=500,dive,id=erf applicationID: type: array x-go-type: '[]*string' description: >- Filter by application ID; null includes flows with no application ID. x-oapi-codegen-extra-tags: validate: omitempty,min=1,dive,omitnil,min=1,max=25 items: type: - string - 'null' customTag1: type: array x-go-type: '[]*string' description: >- Filter by first configured custom tag value; null includes absent or empty values. x-oapi-codegen-extra-tags: validate: omitempty,min=1,dive,omitnil,min=1,max=255 items: type: - string - 'null' customTag2: type: array x-go-type: '[]*string' description: >- Filter by second configured custom tag value; null includes absent or empty values. x-oapi-codegen-extra-tags: validate: omitempty,min=1,dive,omitnil,min=1,max=255 items: type: - string - 'null' customTag3: type: array x-go-type: '[]*string' description: >- Filter by third configured custom tag value; null includes absent or empty values. x-oapi-codegen-extra-tags: validate: omitempty,min=1,dive,omitnil,min=1,max=255 items: type: - string - 'null' customTag4: type: array x-go-type: '[]*string' description: >- Filter by fourth configured custom tag value; null includes absent or empty values. x-oapi-codegen-extra-tags: validate: omitempty,min=1,dive,omitnil,min=1,max=255 items: type: - string - 'null' customTag5: type: array x-go-type: '[]*string' description: >- Filter by fifth configured custom tag value; null includes absent or empty values. x-oapi-codegen-extra-tags: validate: omitempty,min=1,dive,omitnil,min=1,max=255 items: type: - string - 'null' customTag6: type: array x-go-type: '[]*string' description: >- Filter by sixth configured custom tag value; null includes absent or empty values. x-oapi-codegen-extra-tags: validate: omitempty,min=1,dive,omitnil,min=1,max=255 items: type: - string - 'null' resetCount: type: array description: Filter by reset count items: type: integer x-oapi-codegen-extra-tags: validate: omitempty,min=1,dive,min=0,max=255 errorCount: type: array description: Filter by exact error count items: type: integer x-oapi-codegen-extra-tags: validate: omitempty,min=1,dive,min=0,max=255 durationBand: type: array description: >- Filter by flow-duration band. Each token maps to a range on ob_flow.duration; multiple tokens are OR-combined. le3s=<=3s, le10s=<=10s, le30s=<=30s, le1m=<=60s, le5m=<=300s, g5m=>300s. items: type: string enum: - le3s - le10s - le30s - le1m - le5m - g5m x-oapi-codegen-extra-tags: validate: omitempty,min=1,dive,oneof=le3s le10s le30s le1m le5m g5m minErrorCount: type: integer description: >- Filter to flows whose error count is at least this value. Independent from `errorCount` (exact-value set); when both are supplied they are AND-combined. Pass 1 to match errored flows. minimum: 0 maximum: 255 x-oapi-codegen-extra-tags: validate: omitempty,min=0,max=255 experimentID: type: string description: >- Restrict flows to those exposed to this experiment run (format `exp-`). Enables joining variant attribution; each returned flow includes its `variantID`. x-oapi-codegen-extra-tags: validate: omitempty,id=exp variantIDs: type: array description: >- Restrict flows to these experiment variants (format `exv-`). Requires `experimentID`. items: type: string x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=500,dive,id=exv limit: type: integer description: Maximum number of flows to return. Defaults to 100, maximum 10000. default: 100 minimum: 1 maximum: 10000 x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=10000 observeFlowSearchRsp: type: object required: - flows - totalCount properties: flows: type: array description: >- Matching flows in stable timeline order, oldest first, capped at `limit`. items: $ref: '#/components/schemas/observeFlowSearchEntry' totalCount: type: integer description: >- Number of matching flows returned (equal to len(flows), capped at `limit`). This is the exact total when it is below `limit`; when it equals `limit` there may be more matches that were not counted (the endpoint runs no separate COUNT query, for efficiency). observeFlowSearchEntry: type: object required: - flowID - sessionID - flowType - outcome - visitorType - errorCount - resetCount - durationMs - previousTotalCount - previousSameTouchpointCount - createdMs properties: parentFlowID: type: string description: >- Enclosing flow (flw-...), when nested. Older unrefreshed rows may not have this relationship. clientEnvDataID: type: string description: Exact environment snapshot row ID, encoded as a decimal string. longPath: type: string description: Full classified path, preserving technical outcome codes. flowID: type: string description: Flow ID (format `flw-`). sessionID: type: string description: Session ID (UUID format). userID: type: string description: User ID (format `tus-`). Absent for anonymous flows. externalID: type: string description: Customer-provided external user ID. Absent for anonymous flows. clientEnvID: type: string description: >- Client environment ID (format `tce-`). Absent when no client environment was resolved. flowType: type: string description: Flow type (login, enrollment, signup, recovery) outcome: type: string enum: - complete - incomplete - skipped - invisible - visible-auto-skip description: Flow outcome visitorType: type: string enum: - user - auto-test x-enum-varnames: - ObserveFlowSearchEntryVisitorTypeUser - ObserveFlowSearchEntryVisitorTypeAutoTest description: Visitor type classified for the flow. errorCount: type: integer description: Number of errors during the flow. resetCount: type: integer description: Number of resets during the flow. durationMs: type: integer format: int64 description: Duration of the flow in milliseconds. previousFlowDiffMs: type: integer format: int64 description: >- Time since the previous flow for the same user in milliseconds, when available. previousTotalCount: type: integer description: Number of previous flows for the same user. previousSameTouchpointCount: type: integer description: Number of previous flows for the same user and touchpoint. createdMs: description: Flow creation time in milliseconds since epoch type: integer format: int64 osName: type: string description: OS name browserName: type: string description: Browser name osVersion: type: string description: OS major version browserVersion: type: string description: Browser major version model: type: string description: >- Device model from Sec-CH-UA-Model (when the client opted in). Absent on older data and when the header was not sent. uvpaa: type: boolean description: >- Whether a user-verifying platform authenticator was available on the client (isUVPAA). Null on app-only flows and rare web flows missing a capability snapshot. applicationID: type: string description: Application ID touchpoint: type: string description: Flow touchpoint customTag1: type: string description: Value of the first configured custom tag for this flow customTag2: type: string description: Value of the second configured custom tag for this flow customTag3: type: string description: Value of the third configured custom tag for this flow customTag4: type: string description: Value of the fourth configured custom tag for this flow customTag5: type: string description: Value of the fifth configured custom tag for this flow customTag6: type: string description: Value of the sixth configured custom tag for this flow variantID: type: string description: >- Experiment variant the flow was exposed to (format `exv-`). Present only when `experimentID` was supplied in the request. 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 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. ````