> ## Documentation Index
> Fetch the complete documentation index at: https://docs.roark.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# List customer flows

> Returns a paginated list of customer flows with their agents, expectations and variants. The step graph is the one field omitted: reading it walks the project's whole step graph, so it comes back from the single-flow endpoint instead.



## OpenAPI

````yaml /api-reference/openapi.documented.json get /v1/simulation/customer-flow
openapi: 3.1.0
info:
  title: Roark Analytics API
  description: >-
    The Roark Analytics API gives you access to the same API that powers the
    award winning Roark Analytics platform.
  version: 1.0.0
servers:
  - description: Production
    url: https://api.roark.ai
security:
  - Bearer: []
tags:
  - name: Agent
  - name: Agent Endpoint
  - name: Call
  - name: Chat
  - name: Metric
  - name: Metric Policy
  - name: Metric Collection Job
  - name: Simulation Persona
  - name: Simulation Environment
  - name: Simulation Customer Flow
  - name: Simulation Customer Flow Variant
  - name: Simulation Scenario
  - name: Simulation Run Plan
  - name: Simulation Run Plan Job
  - name: Simulation Job
  - name: HTTP Request Definition
  - name: Webhook
  - name: Issue
  - name: Knowledge Base
  - name: Call Analysis
  - name: Health
paths:
  /v1/simulation/customer-flow:
    get:
      tags:
        - Simulation Customer Flow
      summary: List customer flows
      description: >-
        Returns a paginated list of customer flows with their agents,
        expectations and variants. The step graph is the one field omitted:
        reading it walks the project's whole step graph, so it comes back from
        the single-flow endpoint instead.
      operationId: getV1SimulationCustomer-flow
      parameters:
        - in: query
          name: limit
          schema:
            type: integer
            minimum: 1
            maximum: 50
            default: 20
        - in: query
          name: after
          schema:
            type: string
        - in: query
          name: searchText
          schema:
            type: string
        - in: query
          name: mode
          schema:
            type: string
            enum:
              - UNSCRIPTED
              - SCRIPTED
              - VOICEMAIL
        - in: query
          name: includeSystem
          schema:
            type: string
            enum:
              - 'true'
              - 'false'
      responses:
        '200':
          description: List of customer flows
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetCustomerFlowsResponse'
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Validation error
              example:
                type: validation
                code: invalid_parameter
                message: The request was invalid
                param: email
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Authentication error
              example:
                type: authentication
                code: unauthorized
                message: Authentication required
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Permission error
              example:
                type: forbidden
                code: permission_denied
                message: You do not have permission to access this resource
          description: Forbidden
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Rate limit error
              example:
                type: rate_limit
                code: too_many_requests
                message: Rate limit exceeded
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Server error
              example:
                type: internal
                code: internal_error
                message: Internal server error
          description: Internal Server Error
      x-codeSamples:
        - lang: JavaScript
          source: >-
            import Roark from '@roarkanalytics/sdk';


            const client = new Roark({
              bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted
            });


            const simulationCustomerFlows = await
            client.simulationCustomerFlow.list();


            console.log(simulationCustomerFlows.data);
        - lang: Python
          source: |-
            import os
            from roark_analytics import Roark

            client = Roark(
                bearer_token=os.environ.get("ROARK_API_BEARER_TOKEN"),  # This is the default and can be omitted
            )
            simulation_customer_flows = client.simulation_customer_flow.list()
            print(simulation_customer_flows.data)
components:
  schemas:
    GetCustomerFlowsResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/CustomerFlowResponse'
        pagination:
          type: object
          properties:
            total:
              type: number
              description: Total number of items
            hasMore:
              type: boolean
              description: Whether there are more items to fetch
            nextCursor:
              type:
                - string
                - 'null'
              description: Cursor for the next page of items
          required:
            - total
            - hasMore
            - nextCursor
      required:
        - data
        - pagination
      description: Paginated list of customer flows
    ErrorResponse:
      type: object
      properties:
        type:
          type: string
          enum:
            - validation
            - authentication
            - forbidden
            - not_found
            - conflict
            - payment_required
            - rate_limit
            - internal
          description: The error type category
          examples:
            - validation
            - authentication
        code:
          type: string
          description: Machine-readable error code identifier
          examples:
            - invalid_parameter
            - missing_required_field
            - unauthorized
        message:
          type: string
          description: Human-readable error message
          examples:
            - The request was invalid
            - Authentication required
        param:
          type: string
          description: The parameter that caused the error (if applicable)
          examples:
            - email
            - user_id
        details:
          description: Additional error context information
      required:
        - type
        - code
        - message
    CustomerFlowResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
        title:
          type: string
          minLength: 1
        description:
          type:
            - string
            - 'null'
        mode:
          type: string
          enum:
            - UNSCRIPTED
            - SCRIPTED
            - VOICEMAIL
        scriptedBranchingMode:
          type: string
          enum:
            - DETERMINISTIC
            - ADAPTIVE
          default: DETERMINISTIC
        source:
          type: string
          enum:
            - SYSTEM
            - CUSTOM
          default: CUSTOM
        systemKey:
          type:
            - string
            - 'null'
        startNodeId:
          type:
            - string
            - 'null'
          format: uuid
        createdAt:
          type: string
          description: Creation timestamp in ISO 8601 format
        updatedAt:
          type: string
          description: Last update timestamp in ISO 8601 format
        agentIds:
          type: array
          items:
            type: string
            format: uuid
          description: Agents this flow exercises
        agentExpectations:
          type: array
          items:
            $ref: '#/components/schemas/FlowExpectationResponse'
        variants:
          type: array
          items:
            $ref: '#/components/schemas/FlowVariantResponse'
        steps:
          type: array
          items:
            $ref: '#/components/schemas/FlowStep'
          description: The conversation, as a tree of steps. Scripted flows only.
        stepsSharedWithOtherFlows:
          type: array
          items:
            type: string
            format: uuid
          description: >-
            Steps that another flow also uses. Removing one of these detaches it
            from this flow rather than deleting it, so the other flow keeps
            working.
      required:
        - id
        - title
        - mode
        - scriptedBranchingMode
        - source
        - startNodeId
        - createdAt
        - updatedAt
        - agentIds
        - agentExpectations
        - variants
      description: >-
        A customer flow: the conversation a simulated customer has with the
        agent under test. Flows with source SYSTEM are curated by Roark, shared
        across projects, and read-only.
    FlowExpectationResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
        llmPrompt:
          type: string
        orderIndex:
          type: integer
          default: 0
        sourceStepNodeId:
          type:
            - string
            - 'null'
          format: uuid
      required:
        - id
        - llmPrompt
        - orderIndex
        - sourceStepNodeId
      description: >-
        An expectation the agent under test is graded against. On a scripted
        flow these are derived from the agent turns in the graph, so they are
        read-only there.
    FlowVariantResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
        customerFlowId:
          type: string
          format: uuid
        title:
          type: string
          minLength: 1
        isDefault:
          type: boolean
          default: false
        personaId:
          type:
            - string
            - 'null'
          format: uuid
        environmentId:
          type:
            - string
            - 'null'
          format: uuid
        prompt:
          type:
            - string
            - 'null'
        latestPathId:
          type:
            - string
            - 'null'
          format: uuid
        precededByCustomerFlowId:
          type:
            - string
            - 'null'
          format: uuid
        precededByCustomerFlowVariantId:
          type:
            - string
            - 'null'
          format: uuid
        isGenerated:
          type: boolean
          default: false
        isAutoGeneratedTitle:
          type: boolean
          default: false
        createdAt:
          type: string
          description: Creation timestamp in ISO 8601 format
        updatedAt:
          type: string
          description: Last update timestamp in ISO 8601 format
        additionalExpectations:
          type: array
          items:
            $ref: '#/components/schemas/FlowExpectationResponse'
      required:
        - id
        - customerFlowId
        - title
        - isDefault
        - personaId
        - environmentId
        - latestPathId
        - precededByCustomerFlowId
        - precededByCustomerFlowVariantId
        - isGenerated
        - isAutoGeneratedTitle
        - createdAt
        - updatedAt
        - additionalExpectations
      description: >-
        One way of running a flow. Exactly one variant per flow is the default;
        the others inherit its persona and environment wherever they leave those
        unset. On a scripted flow each variant is bound to one path through the
        graph and the path engine owns that binding.
    FlowStep:
      type: object
      properties:
        nodeId:
          type: string
          format: uuid
        ref:
          type: string
          minLength: 1
          maxLength: 64
        type:
          type: string
          enum:
            - AGENT_TURN
            - CUSTOMER_TURN
            - CUSTOMER_FIRST_MESSAGE
            - CUSTOMER_SILENCE
            - CUSTOMER_DTMF
            - VOICEMAIL
            - SCENARIO_LINK
        content:
          type:
            - string
            - 'null'
        dtmfDigits:
          type:
            - string
            - 'null'
        silenceDurationSeconds:
          type:
            - integer
            - 'null'
          exclusiveMinimum: 0
        linkedCustomerFlowId:
          type:
            - string
            - 'null'
          format: uuid
        linkedCustomerFlowVariantId:
          type:
            - string
            - 'null'
          format: uuid
        steps:
          type: array
          items:
            $ref: '#/components/schemas/FlowStep'
        mergeIntoNodeIds:
          type: array
          items:
            type: string
            minLength: 1
      required:
        - type
      description: >-
        One step in a scripted flow's conversation.


        `nodeId` is the identity contract: include it to update the existing
        step, omit it to create a new one.

        A step continues into `steps` (more than one child is a branch point)
        and/or `mergeIntoNodeIds`, which

        names steps elsewhere in the same request that this step rejoins.
        Branches that come back together are

        represented that way rather than by repeating the shared step, so
        reading a flow, editing it and writing

        it back preserves it exactly.


        A merge target is named by its `nodeId` when it already exists, or by
        `ref` when it is being created in

        the same request. `ref` is a label you choose, it is request-local, and
        it is never stored or returned.

        Put the shared step inline under the first branch that reaches it and
        point the others at it: a top-level

        step is a root wired straight from the start of the flow, so a merge
        target parked there would also be

        reachable directly.
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT

````