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

# List flow versions

> Lists the saved versions of a flow, newest first. A version is recorded when the flow is published, restored, imported, duplicated or saved by hand. Each one says when it was made, its `origin`, who made it and whether it came from restoring an older one (`isRestored`, `restoredFromId`).

`hasDanglingReferences` is `true` when a version has edges pointing at groups or blocks that no longer exist. Such a version is broken; do not restore it.

Each entry carries the version's full content unless `excludeContent` is `true`, and that is large. List with `excludeContent=true`, then read one version with `historyId`. Page with `nextCursor`: pass it back as `cursor` until it is `null`.



## OpenAPI

````yaml /api-reference/specs/controlled-flows/v1.json get /v1/typebots/{flowId}/history
openapi: 3.0.3
info:
  title: Controlled Flows API
  version: 1.0.0
  description: >-
    Read, build, validate and publish controlled flows and the tools agents
    call.
servers:
  - url: https://api.cloudhumans.com/typebot
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Workspaces
    description: The workspaces that hold your flows.
  - name: Flows
    description: >-
      Read, create, change, validate and publish flows. Writes land in the
      draft; only a publish makes them live.
  - name: Versions
    description: The saved versions of a flow, and restoring one.
  - name: Credentials
    description: >-
      REST API credentials that HTTP Request blocks send without exposing the
      secret in the flow.
paths:
  /v1/typebots/{flowId}/history:
    get:
      tags:
        - Versions
      summary: List flow versions
      description: >-
        Lists the saved versions of a flow, newest first. A version is recorded
        when the flow is published, restored, imported, duplicated or saved by
        hand. Each one says when it was made, its `origin`, who made it and
        whether it came from restoring an older one (`isRestored`,
        `restoredFromId`).


        `hasDanglingReferences` is `true` when a version has edges pointing at
        groups or blocks that no longer exist. Such a version is broken; do not
        restore it.


        Each entry carries the version's full content unless `excludeContent` is
        `true`, and that is large. List with `excludeContent=true`, then read
        one version with `historyId`. Page with `nextCursor`: pass it back as
        `cursor` until it is `null`.
      operationId: listFlowVersions
      parameters:
        - name: flowId
          in: path
          required: true
          description: >-
            The flow's internal id, e.g. `clx9z8y7x6w5v4u3t2s1`. Get it from
            **List flows** (the `id` field of each flow). It is NOT the
            `publicId` slug that appears in a flow's public URL: a slug answers
            404 here. A flow your token cannot reach answers 404,
            indistinguishable from one that does not exist.
          schema:
            type: string
        - name: limit
          in: query
          required: false
          description: >-
            How many entries to return, from 1 to 100. Defaults to 20. Keep it
            small when `excludeContent` is not `true`.
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
          example: 20
        - name: cursor
          in: query
          required: false
          description: >-
            Where to resume: the `nextCursor` of the previous page. Omit for the
            first page.
          schema:
            type: string
        - name: excludeContent
          in: query
          required: false
          description: >-
            When `true`, entries come without the snapshot's flow content — just
            who, when and which origin. Send `true` whenever you are listing
            versions; leave it out only to read a single snapshot with
            `historyId`. Without it every entry carries a complete copy of the
            flow.
          schema:
            type: boolean
        - name: historyId
          in: query
          required: false
          description: >-
            Return only this snapshot, by its `id` from an earlier listing of
            this flow's history. A snapshot of another flow answers an empty
            list.
          schema:
            type: string
      responses:
        '200':
          description: One page of snapshots, newest first.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlowVersionPage'
        '400':
          description: >-
            The request could not be answered as written. `message` says which
            input was rejected.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing, expired or invalid credentials.
        '404':
          description: >-
            No such resource, or none your token can reach — the two are
            deliberately indistinguishable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit applied by the API gateway. Back off and retry.
components:
  schemas:
    FlowVersionPage:
      type: object
      required:
        - history
      properties:
        history:
          type: array
          items:
            $ref: '#/components/schemas/FlowVersion'
          description: The snapshots on this page, newest first.
        nextCursor:
          nullable: true
          type: string
          description: Pass as `cursor` to read the next page. Null on the last page.
        totalCount:
          type: integer
          description: How many snapshots the flow has (or 1 when `historyId` was sent).
      description: One page of a flow's version history.
    Error:
      type: object
      properties:
        message:
          type: string
          description: What went wrong.
        code:
          type: string
          description: Error code, e.g. `NOT_FOUND` or `BAD_REQUEST`.
        issues:
          type: array
          description: Per-field validation problems, present on a 400 for invalid input.
          items:
            type: object
            additionalProperties: true
      required:
        - message
        - code
      description: Something the caller needs to fix.
    FlowVersion:
      type: object
      required:
        - id
      properties:
        id:
          type: string
          description: The snapshot's id — the `historyId` to read just this one.
        createdAt:
          type: string
          format: date-time
          description: When the snapshot was recorded.
        origin:
          type: string
          description: What recorded it.
          enum:
            - PUBLISH
            - DUPLICATION
            - MANUAL
            - IMPORT
            - RESTORE
        version:
          type: string
          description: >-
            The flow schema version the snapshot was saved with. Empty when
            unknown.
        isRestored:
          type: boolean
          description: True when this snapshot was made by restoring an older one.
        restoredFromId:
          nullable: true
          type: string
          description: >-
            The snapshot this one restored. Null when it did not come from a
            restore.
        publishedAt:
          nullable: true
          type: string
          format: date-time
          description: When this snapshot went live. Null when it was never published.
        author:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/FlowVersionAuthor'
          description: Who made the snapshot. Null when the author is unknown.
        hasDanglingReferences:
          type: boolean
          description: >-
            True when the snapshot has edges pointing at groups or blocks that
            do not exist. Such a snapshot is broken.
        content:
          $ref: '#/components/schemas/FlowVersionContent'
      description: One saved version of a flow.
    FlowVersionAuthor:
      type: object
      properties:
        id:
          type: string
          description: The author's user id.
        name:
          nullable: true
          type: string
          description: The author's name.
        email:
          nullable: true
          type: string
          description: The author's email.
      description: Who made a snapshot.
    FlowVersionContent:
      type: object
      properties:
        name:
          type: string
          description: The flow's name in this snapshot.
        icon:
          nullable: true
          type: string
          description: The flow's icon in this snapshot.
        groups:
          nullable: true
          type: array
          items:
            type: object
            additionalProperties: true
          description: The groups in this snapshot.
        edges:
          nullable: true
          type: array
          items:
            type: object
            additionalProperties: true
          description: The edges in this snapshot.
        events:
          nullable: true
          type: array
          items:
            type: object
            additionalProperties: true
          description: The start event(s) in this snapshot.
        variables:
          nullable: true
          type: array
          items:
            type: object
            additionalProperties: true
          description: The variables in this snapshot.
        settings:
          nullable: true
          type: object
          additionalProperties: true
          description: The settings in this snapshot.
        tenant:
          nullable: true
          type: string
          description: >-
            The tool's tenant in this snapshot. Null for snapshots recorded
            before history stored it.
        toolDescription:
          nullable: true
          type: string
          description: >-
            The tool's description in this snapshot. Null for snapshots recorded
            before history stored it.
      description: >-
        The flow as it was in a snapshot. Present only when `excludeContent` was
        not `true`.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.