# Source: https://planetscale.com/docs/api/reference/list_deploy_requests.md

# List deploy requests

> List deploy requests for a database
### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:

**Service Token Accesses**
 `read_deploy_request`

**OAuth Scopes**

 | Resource | Scopes |
| :------- | :---------- |
| Organization | `read_deploy_requests` |
| Database | `read_deploy_requests` |



## OpenAPI

````yaml get /organizations/{organization}/databases/{database}/deploy-requests
openapi: 3.0.1
info:
  title: PlanetScale API
  description: |-

    <p>PlanetScale API</p>
    &copy; 2025 PlanetScale, Inc.
  version: v1
  x-copyright: '&copy; 2025 PlanetScale, Inc.'
servers:
  - url: https://api.planetscale.com/v1
security:
  - ApiKeyHeader:
      - Authorization
tags:
  - name: Backups
    description: |2
                Resources for managing database branch backups.
  - name: Branch changes
    description: |2
                Resources for managing cluster changes.
  - name: Cluster extensions
    description: |2
                Resources for managing cluster extension configuration.
  - name: Branch log signatures
    description: |2
                Resources for retrieving branch log access signatures.
  - name: Cluster parameters
    description: |2
                Resources for managing cluster configuration parameters.
  - name: Database branch keyspaces
    description: |2
                Resources for managing keyspaces.
  - name: Database branch passwords
    description: |2
                Resources for managing database branch passwords.
  - name: Database Postgres IP restrictions
    description: |2
                Resources for managing Postgres IP restriction entries for databases.

                Note: This endpoint is only available for PostgreSQL databases. For MySQL databases, use the Database Branch Passwords endpoint.
  - name: Databases
    description: |2
                  Resources for managing databases within an organization.
  - name: Keyspace VSchemas
    description: |2
                Resources for managing VSchemas within a keyspace.
  - name: OAuth applications
    description: |2
                Resources for managing OAuth applications.
  - name: OAuth tokens
    description: |2
                Resources for managing OAuth tokens.
  - name: Organization members
    description: |2
                Resources for managing organization members and their roles.
  - name: Organizations
    description: |2
                  Resources for managing organizations.
  - name: Bouncer resizes
    description: |2
                Resources for managing Postgres bouncer resize requests.
  - name: Bouncers
    description: |2
                Resources for managing postgres bouncers.
  - name: Roles
    description: |2
                Resources for managing role credentials.
  - name: Query Insights reports
    description: |2
                Resources for downloading query insights data.
  - name: Service tokens
    description: |2
                API endpoints for managing service tokens within an organization.
  - name: Users
    description: |2
                Resources for managing users.
  - name: Workflows
    description: |2
                API endpoints for managing workflows.
  - name: Deploy requests
    description: |2
                  Resources for managing deploy requests.
  - name: Webhooks
    description: |2
                  Resources for managing database webhooks.
  - name: Invoices
    description: |2
                  Resources for managing invoices.
  - name: Organization teams
    description: |2
                  Resources for managing teams within an organization. Teams allow you to group members and grant them access to specific databases.

                  Note: Teams managed through SSO/directory services cannot be modified via API.
paths:
  /organizations/{organization}/databases/{database}/deploy-requests:
    get:
      tags:
        - Deploy requests
      summary: List deploy requests
      description: >-
        List deploy requests for a database

        ### Authorization

        A service token or OAuth token must have at least one of the following
        access or scopes in order to use this API endpoint:


        **Service Token Accesses**
         `read_deploy_request`

        **OAuth Scopes**

         | Resource | Scopes |
        | :------- | :---------- |

        | Organization | `read_deploy_requests` |

        | Database | `read_deploy_requests` |
      operationId: list_deploy_requests
      parameters:
        - name: organization
          in: path
          required: true
          description: The name of the deploy request's organization
          schema:
            type: string
        - name: database
          in: path
          required: true
          description: The name of the deploy request's database
          schema:
            type: string
        - name: state
          in: query
          description: Filter by state of the deploy request (open, closed, deployed)
          schema:
            type: string
        - name: branch
          in: query
          description: Filter by the name of the branch the deploy request is created from
          schema:
            type: string
        - name: into_branch
          in: query
          description: >-
            Filter by the name of the branch the deploy request will be merged
            into
          schema:
            type: string
        - name: deployed_at
          in: query
          description: >-
            Filter deploy requests by the date they were deployed. (e.g.
            2023-01-01T00:00:00Z..2023-01-31T23:59:59Z)
          schema:
            type: string
        - name: running_at
          in: query
          description: >-
            Filter deploy requests by the date they were running. (e.g.
            2023-01-01T00:00:00Z..2023-01-31T23:59:59Z)
          schema:
            type: string
        - name: page
          in: query
          description: If provided, specifies the page offset of returned results
          schema:
            type: integer
            default: 1
        - name: per_page
          in: query
          description: If provided, specifies the number of returned results
          schema:
            type: integer
            default: 25
      responses:
        '200':
          description: Returns a list of deploy requests
          headers: {}
          content:
            application/json:
              schema:
                type: object
                properties:
                  current_page:
                    type: integer
                    description: The current page number
                  next_page:
                    type: integer
                    description: The next page number
                  next_page_url:
                    type: string
                    description: The next page of results
                  prev_page:
                    type: integer
                    description: The previous page number
                  prev_page_url:
                    type: string
                    description: The previous page of results
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          description: The ID of the deploy request
                        number:
                          type: integer
                          description: The number of the deploy request
                        actor:
                          type: object
                          properties:
                            id:
                              type: string
                              description: The ID of the actor
                            display_name:
                              type: string
                              description: The name of the actor
                            avatar_url:
                              type: string
                              description: The URL of the actor's avatar
                          additionalProperties: false
                          required:
                            - id
                            - display_name
                            - avatar_url
                        closed_by:
                          type: object
                          properties:
                            id:
                              type: string
                              description: The ID of the actor
                            display_name:
                              type: string
                              description: The name of the actor
                            avatar_url:
                              type: string
                              description: The URL of the actor's avatar
                          additionalProperties: false
                          required:
                            - id
                            - display_name
                            - avatar_url
                        branch:
                          type: string
                          description: >-
                            The name of the branch the deploy request was
                            created from
                        branch_id:
                          type: string
                          description: >-
                            The ID of the branch the deploy request was created
                            from
                        branch_deleted:
                          type: boolean
                          description: Whether or not the deploy request branch was deleted
                        branch_deleted_by:
                          type: object
                          properties:
                            id:
                              type: string
                              description: The ID of the actor
                            display_name:
                              type: string
                              description: The name of the actor
                            avatar_url:
                              type: string
                              description: The URL of the actor's avatar
                          additionalProperties: false
                          required:
                            - id
                            - display_name
                            - avatar_url
                        branch_deleted_at:
                          type: string
                          description: When the deploy request branch was deleted
                        into_branch:
                          type: string
                          description: >-
                            The name of the branch the deploy request will be
                            merged into
                        into_branch_sharded:
                          type: boolean
                          description: >-
                            Whether or not the branch the deploy request will be
                            merged into is sharded
                        into_branch_shard_count:
                          type: integer
                          description: >-
                            The number of shards the branch the deploy request
                            will be merged into has
                        approved:
                          type: boolean
                          description: Whether or not the deploy request is approved
                        state:
                          type: string
                          enum:
                            - open
                            - closed
                          description: Whether the deploy request is open or closed
                        deployment_state:
                          type: string
                          enum:
                            - pending
                            - ready
                            - no_changes
                            - queued
                            - submitting
                            - in_progress
                            - pending_cutover
                            - in_progress_vschema
                            - in_progress_cancel
                            - in_progress_cutover
                            - complete
                            - complete_cancel
                            - complete_error
                            - complete_pending_revert
                            - in_progress_revert
                            - in_progress_revert_vschema
                            - complete_revert
                            - complete_revert_error
                            - cancelled
                            - error
                          description: The deployment state of the deploy request
                        deployment:
                          type: object
                          properties:
                            id:
                              type: string
                              description: The ID of the deployment
                            auto_cutover:
                              type: boolean
                              description: >-
                                Whether or not to automatically cutover once
                                deployment is finished
                            auto_delete_branch:
                              type: boolean
                              description: >-
                                Whether or not to automatically delete the head
                                branch once deployment is finished
                            created_at:
                              type: string
                              description: When the deployment was created
                            cutover_at:
                              type: string
                              description: >-
                                When the cutover for the deployment was
                                initiated
                            cutover_expiring:
                              type: boolean
                              description: >-
                                Whether or not the deployment cutover will
                                expire soon
                            deploy_check_errors:
                              type: string
                              description: Deploy check errors for the deployment
                            finished_at:
                              type: string
                              description: When the deployment was finished
                            queued_at:
                              type: string
                              description: When the deployment was queued
                            ready_to_cutover_at:
                              type: string
                              description: When the deployment was ready for cutover
                            started_at:
                              type: string
                              description: When the deployment was started
                            state:
                              type: string
                              enum:
                                - pending
                                - ready
                                - no_changes
                                - queued
                                - submitting
                                - in_progress
                                - pending_cutover
                                - in_progress_vschema
                                - in_progress_cancel
                                - in_progress_cutover
                                - complete
                                - complete_cancel
                                - complete_error
                                - complete_pending_revert
                                - in_progress_revert
                                - in_progress_revert_vschema
                                - complete_revert
                                - complete_revert_error
                                - cancelled
                                - error
                              description: The state the deployment is in
                            submitted_at:
                              type: string
                              description: When the deployment was submitted
                            updated_at:
                              type: string
                              description: When the deployment was last updated
                            into_branch:
                              type: string
                              description: >-
                                The name of the base branch the deployment will
                                be merged into
                            deploy_request_number:
                              type: integer
                              description: >-
                                The number of the deploy request associated with
                                this deployment
                            deployable:
                              type: boolean
                              description: Whether the deployment is deployable
                            preceding_deployments:
                              items:
                                type: object
                                additionalProperties: true
                              type: array
                              description: The deployments ahead of this one in the queue
                            deploy_operations:
                              type: array
                              items:
                                type: object
                                properties:
                                  id:
                                    type: string
                                    description: The ID for the deploy operation
                                  state:
                                    type: string
                                    enum:
                                      - pending
                                      - queued
                                      - in_progress
                                      - complete
                                      - cancelled
                                      - error
                                    description: The state of the deploy operation
                                  keyspace_name:
                                    type: string
                                    description: >-
                                      The keyspace modified by the deploy
                                      operation
                                  table_name:
                                    type: string
                                    description: >-
                                      The name of the table modifed by the
                                      deploy operation
                                  operation_name:
                                    type: string
                                    description: The operation name of the deploy operation
                                  eta_seconds:
                                    type: number
                                    description: >-
                                      The estimated seconds until completion for
                                      the deploy operation
                                  progress_percentage:
                                    type: number
                                    description: >-
                                      The percent completion for the deploy
                                      operation
                                  deploy_error_docs_url:
                                    type: string
                                    description: >-
                                      A link to documentation explaining the
                                      deploy error, if present
                                  ddl_statement:
                                    type: string
                                    description: The DDL statement for the deploy operation
                                  syntax_highlighted_ddl:
                                    type: string
                                    description: >-
                                      A syntax-highlighted DDL statement for the
                                      deploy operation
                                  created_at:
                                    type: string
                                    description: When the deploy operation was created
                                  updated_at:
                                    type: string
                                    description: When the deploy operation was last updated
                                  throttled_at:
                                    type: string
                                    description: >-
                                      When the deploy operation was last
                                      throttled
                                  can_drop_data:
                                    type: boolean
                                    description: >-
                                      Whether or not the deploy operation is
                                      capable of dropping data
                                  table_locked:
                                    type: boolean
                                    description: >-
                                      Whether or not the table modified by the
                                      deploy operation is currently locked
                                  table_recently_used:
                                    type: boolean
                                    description: >-
                                      Whether or not the table modified by the
                                      deploy operation was recently used
                                  table_recently_used_at:
                                    type: string
                                    description: >-
                                      When the table modified by the deploy
                                      operation was last used
                                  removed_foreign_key_names:
                                    items:
                                      type: string
                                    type: array
                                    description: >-
                                      Names of foreign keys removed by this
                                      operation
                                  deploy_errors:
                                    type: string
                                    description: Deploy errors for the deploy operation
                                additionalProperties: false
                                required:
                                  - id
                                  - state
                                  - keyspace_name
                                  - table_name
                                  - operation_name
                                  - eta_seconds
                                  - progress_percentage
                                  - deploy_error_docs_url
                                  - ddl_statement
                                  - syntax_highlighted_ddl
                                  - created_at
                                  - updated_at
                                  - throttled_at
                                  - can_drop_data
                                  - table_locked
                                  - table_recently_used
                                  - table_recently_used_at
                                  - removed_foreign_key_names
                                  - deploy_errors
                            deploy_operation_summaries:
                              type: array
                              items:
                                type: object
                                properties:
                                  id:
                                    type: string
                                    description: The ID for the deploy operation summary
                                  created_at:
                                    type: string
                                    description: >-
                                      When the deploy operation summary was
                                      created
                                  deploy_errors:
                                    type: string
                                    description: >-
                                      Deploy errors for the deploy operation
                                      summary
                                  ddl_statement:
                                    type: string
                                    description: >-
                                      The DDL statement for the deploy operation
                                      summary
                                  eta_seconds:
                                    type: integer
                                    description: >-
                                      The estimated seconds until completion for
                                      the deploy operation summary
                                  keyspace_name:
                                    type: string
                                    description: >-
                                      The keyspace modified by the deploy
                                      operation summary
                                  operation_name:
                                    type: string
                                    description: >-
                                      The operation name of the deploy operation
                                      summary
                                  progress_percentage:
                                    type: number
                                    description: >-
                                      The percent completion for the deploy
                                      operation summary
                                  state:
                                    type: string
                                    enum:
                                      - pending
                                      - in_progress
                                      - complete
                                      - cancelled
                                      - error
                                    description: The state of the deploy operation summary
                                  syntax_highlighted_ddl:
                                    type: string
                                    description: >-
                                      A syntax-highlighted DDL statement for the
                                      deploy operation summary
                                  table_name:
                                    type: string
                                    description: >-
                                      The name of the table modifed by the
                                      deploy operation summary
                                  table_recently_used_at:
                                    type: string
                                    description: >-
                                      When the table modified by the deploy
                                      operation summary was last used
                                  throttled_at:
                                    type: string
                                    description: >-
                                      When the deploy operation summary was last
                                      throttled
                                  removed_foreign_key_names:
                                    items:
                                      type: string
                                    type: array
                                    description: >-
                                      Names of foreign keys removed by this
                                      operation summary
                                  shard_count:
                                    type: integer
                                    description: >-
                                      The number of shards in the keyspace
                                      modified by the deploy operation summary
                                  shard_names:
                                    items:
                                      type: string
                                    type: array
                                    description: >-
                                      Names of shards in the keyspace modified
                                      by the deploy operation summary
                                  can_drop_data:
                                    type: boolean
                                    description: >-
                                      Whether or not the deploy operation
                                      summary is capable of dropping data
                                  table_recently_used:
                                    type: boolean
                                    description: >-
                                      Whether or not the table modified by the
                                      deploy operation summary was recently used
                                  sharded:
                                    type: boolean
                                    description: >-
                                      Whether or not the keyspace modified by
                                      the deploy operation summary is sharded
                                  operations:
                                    type: array
                                    items:
                                      type: object
                                      properties:
                                        id:
                                          type: string
                                          description: The ID for the deploy operation
                                        shard:
                                          type: string
                                          description: >-
                                            The shard the deploy operation is being
                                            performed on
                                        state:
                                          type: string
                                          enum:
                                            - pending
                                            - queued
                                            - in_progress
                                            - complete
                                            - cancelled
                                            - error
                                          description: The state of the deploy operation
                                        progress_percentage:
                                          type: number
                                          description: >-
                                            The percent completion for the deploy
                                            operation
                                        eta_seconds:
                                          type: integer
                                          description: >-
                                            The estimated seconds until completion
                                            for the deploy operation
                                      additionalProperties: false
                                      required:
                                        - id
                                        - shard
                                        - state
                                        - progress_percentage
                                        - eta_seconds
                                additionalProperties: false
                                required:
                                  - id
                                  - created_at
                                  - deploy_errors
                                  - ddl_statement
                                  - eta_seconds
                                  - keyspace_name
                                  - operation_name
                                  - progress_percentage
                                  - state
                                  - syntax_highlighted_ddl
                                  - table_name
                                  - table_recently_used_at
                                  - throttled_at
                                  - removed_foreign_key_names
                                  - shard_count
                                  - shard_names
                                  - can_drop_data
                                  - table_recently_used
                                  - sharded
                                  - operations
                            lint_errors:
                              items:
                                type: object
                                additionalProperties: true
                              type: array
                              description: >-
                                Schema lint errors preventing the deployment
                                from completing
                            sequential_diff_dependencies:
                              items:
                                type: object
                                additionalProperties: true
                              type: array
                              description: The schema dependencies that must be satisfied
                            lookup_vindex_operations:
                              items:
                                type: object
                                additionalProperties: true
                              type: array
                              description: Lookup Vitess index operations
                            throttler_configurations:
                              items:
                                type: object
                                additionalProperties: true
                              type: array
                              description: Deployment throttling configurations
                            deployment_revert_request:
                              type: object
                              additionalProperties: true
                              description: >-
                                The request to revert the schema operations in
                                this deployment
                            actor:
                              type: object
                              properties:
                                id:
                                  type: string
                                  description: The ID of the actor
                                display_name:
                                  type: string
                                  description: The name of the actor
                                avatar_url:
                                  type: string
                                  description: The URL of the actor's avatar
                              additionalProperties: false
                              required:
                                - id
                                - display_name
                                - avatar_url
                            cutover_actor:
                              type: object
                              properties:
                                id:
                                  type: string
                                  description: The ID of the actor
                                display_name:
                                  type: string
                                  description: The name of the actor
                                avatar_url:
                                  type: string
                                  description: The URL of the actor's avatar
                              additionalProperties: false
                              required:
                                - id
                                - display_name
                                - avatar_url
                            cancelled_actor:
                              type: object
                              properties:
                                id:
                                  type: string
                                  description: The ID of the actor
                                display_name:
                                  type: string
                                  description: The name of the actor
                                avatar_url:
                                  type: string
                                  description: The URL of the actor's avatar
                              additionalProperties: false
                              required:
                                - id
                                - display_name
                                - avatar_url
                            schema_last_updated_at:
                              type: string
                              description: >-
                                When the schema was last updated for the
                                deployment
                            table_locked:
                              type: boolean
                              description: Whether or not the deployment has a table locked
                            locked_table_name:
                              type: string
                              description: >-
                                The name of he table that is locked by the
                                deployment
                            instant_ddl:
                              type: boolean
                              description: >-
                                Whether or not the deployment is an instant DDL
                                deployment
                            instant_ddl_eligible:
                              type: boolean
                              description: >-
                                Whether or not the deployment is eligible for
                                instant DDL
                          additionalProperties: false
                          required:
                            - id
                            - auto_cutover
                            - auto_delete_branch
                            - created_at
                            - cutover_at
                            - cutover_expiring
                            - deploy_check_errors
                            - finished_at
                            - queued_at
                            - ready_to_cutover_at
                            - started_at
                            - state
                            - submitted_at
                            - updated_at
                            - into_branch
                            - deploy_request_number
                            - deployable
                            - preceding_deployments
                            - deploy_operations
                            - deploy_operation_summaries
                            - lint_errors
                            - sequential_diff_dependencies
                            - lookup_vindex_operations
                            - throttler_configurations
                            - deployment_revert_request
                            - actor
                            - cutover_actor
                            - cancelled_actor
                            - schema_last_updated_at
                            - table_locked
                            - locked_table_name
                            - instant_ddl
                            - instant_ddl_eligible
                        num_comments:
                          type: integer
                          description: The number of comments on the deploy request
                        html_url:
                          type: string
                          description: The PlanetScale app address for the deploy request
                        notes:
                          type: string
                          description: Notes on the deploy request
                        html_body:
                          type: string
                          description: The HTML body of the deploy request
                        created_at:
                          type: string
                          description: When the deploy request was created
                        updated_at:
                          type: string
                          description: When the deploy request was last updated
                        closed_at:
                          type: string
                          description: When the deploy request was closed
                        deployed_at:
                          type: string
                          description: When the deploy request was deployed
                      additionalProperties: false
                      required:
                        - id
                        - number
                        - actor
                        - closed_by
                        - branch
                        - branch_id
                        - branch_deleted
                        - branch_deleted_by
                        - branch_deleted_at
                        - into_branch
                        - into_branch_sharded
                        - into_branch_shard_count
                        - approved
                        - state
                        - deployment_state
                        - deployment
                        - num_comments
                        - html_url
                        - notes
                        - html_body
                        - created_at
                        - updated_at
                        - closed_at
                        - deployed_at
                additionalProperties: false
                required:
                  - current_page
                  - next_page
                  - next_page_url
                  - prev_page
                  - prev_page_url
                  - data
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
        '500':
          description: Internal Server Error
components:
  securitySchemes:
    ApiKeyHeader:
      type: apiKey
      in: header
      name: Authorization

````

---

> To find navigation and other pages in this documentation, fetch the llms.txt file at: https://planetscale.com/llms.txt