List databases

curl --request GET \
  --url https://api.planetscale.com/v1/organizations/{organization}/databases \
  --header 'Authorization: <api-key>'

{
  "current_page": 123,
  "next_page": 123,
  "next_page_url": "<string>",
  "prev_page": 123,
  "prev_page_url": "<string>",
  "data": [
    {
      "id": "<string>",
      "url": "<string>",
      "branches_url": "<string>",
      "branches_count": 123,
      "open_schema_recommendations_count": 123,
      "development_branches_count": 123,
      "production_branches_count": 123,
      "issues_count": 123,
      "multiple_admins_required_for_deletion": true,
      "ready": true,
      "at_backup_restore_branches_limit": true,
      "at_development_branch_usage_limit": true,
      "data_import": {
        "state": "<string>",
        "import_check_errors": "<string>",
        "started_at": "<string>",
        "finished_at": "<string>",
        "data_source": {
          "hostname": "<string>",
          "port": 123,
          "database": "<string>"
        }
      },
      "region": {
        "id": "<string>",
        "provider": "<string>",
        "enabled": true,
        "public_ip_addresses": [
          "<string>"
        ],
        "display_name": "<string>",
        "location": "<string>",
        "slug": "<string>",
        "current_default": true
      },
      "html_url": "<string>",
      "name": "<string>",
      "state": "pending",
      "sharded": true,
      "default_branch_shard_count": 123,
      "default_branch_read_only_regions_count": 123,
      "default_branch_table_count": 123,
      "default_branch": "<string>",
      "require_approval_for_deploy": true,
      "resizing": true,
      "resize_queued": true,
      "allow_data_branching": true,
      "foreign_keys_enabled": true,
      "automatic_migrations": true,
      "restrict_branch_region": true,
      "insights_raw_queries": true,
      "plan": "<string>",
      "insights_enabled": true,
      "production_branch_web_console": true,
      "migration_table_name": "<string>",
      "migration_framework": "<string>",
      "created_at": "<string>",
      "updated_at": "<string>",
      "schema_last_updated_at": "<string>",
      "kind": "mysql"
    }
  ]
}

Databases

List databases

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_database, delete_database, write_database, read_branch, delete_branch, create_branch, delete_production_branch, connect_branch, connect_production_branch, delete_branch_password, delete_production_branch_password, read_deploy_request, create_deploy_request, approve_deploy_request, read_schema_recommendations, close_schema_recommendations, read_comment, create_comment, restore_backup, restore_production_branch_backup, read_backups, write_backups, delete_backups, delete_production_branch_backups, write_branch_vschema, write_production_branch_vschema

OAuth Scopes

Resource	Scopes
Organization	`read_databases`

GET

organizations

{organization}

databases

List databases

curl --request GET \
  --url https://api.planetscale.com/v1/organizations/{organization}/databases \
  --header 'Authorization: <api-key>'

{
  "current_page": 123,
  "next_page": 123,
  "next_page_url": "<string>",
  "prev_page": 123,
  "prev_page_url": "<string>",
  "data": [
    {
      "id": "<string>",
      "url": "<string>",
      "branches_url": "<string>",
      "branches_count": 123,
      "open_schema_recommendations_count": 123,
      "development_branches_count": 123,
      "production_branches_count": 123,
      "issues_count": 123,
      "multiple_admins_required_for_deletion": true,
      "ready": true,
      "at_backup_restore_branches_limit": true,
      "at_development_branch_usage_limit": true,
      "data_import": {
        "state": "<string>",
        "import_check_errors": "<string>",
        "started_at": "<string>",
        "finished_at": "<string>",
        "data_source": {
          "hostname": "<string>",
          "port": 123,
          "database": "<string>"
        }
      },
      "region": {
        "id": "<string>",
        "provider": "<string>",
        "enabled": true,
        "public_ip_addresses": [
          "<string>"
        ],
        "display_name": "<string>",
        "location": "<string>",
        "slug": "<string>",
        "current_default": true
      },
      "html_url": "<string>",
      "name": "<string>",
      "state": "pending",
      "sharded": true,
      "default_branch_shard_count": 123,
      "default_branch_read_only_regions_count": 123,
      "default_branch_table_count": 123,
      "default_branch": "<string>",
      "require_approval_for_deploy": true,
      "resizing": true,
      "resize_queued": true,
      "allow_data_branching": true,
      "foreign_keys_enabled": true,
      "automatic_migrations": true,
      "restrict_branch_region": true,
      "insights_raw_queries": true,
      "plan": "<string>",
      "insights_enabled": true,
      "production_branch_web_console": true,
      "migration_table_name": "<string>",
      "migration_framework": "<string>",
      "created_at": "<string>",
      "updated_at": "<string>",
      "schema_last_updated_at": "<string>",
      "kind": "mysql"
    }
  ]
}

Authorizations

Authorization

string

header

required

Path Parameters

organization

string

required

The name of the organization the database belongs to

Query Parameters

string

Search term to filter databases by name

page

integer

default:1

If provided, specifies the page offset of returned results

per_page

integer

default:25

If provided, specifies the number of returned results

Response

Retrieves the databases for an organization

current_page

integer

required

The current page number

next_page

integer

required

The next page number

next_page_url

string

required

The next page of results

prev_page

integer

required

The previous page number

prev_page_url

string

required

The previous page of results

data

object[]

required

Show child attributes

data.id

string

required

The ID of the database

data.url

string

required

The URL to the database API endpoint

data.branches_url

string

required

The URL to retrieve this database's branches via the API

data.branches_count

integer

required

The total number of database branches

data.open_schema_recommendations_count

integer

required

The total number of schema recommendations

data.development_branches_count

integer

required

The total number of database development branches

data.production_branches_count

integer

required

The total number of database production branches

data.issues_count

integer

required

The total number of ongoing issues within a database

data.multiple_admins_required_for_deletion

boolean

required

If the database requires multiple admins for deletion

data.ready

boolean

required

If the database is ready to be used

data.at_backup_restore_branches_limit

boolean

required

If the database has reached its backup restored branch limit

data.at_development_branch_usage_limit

boolean

required

If the database has reached its development branch limit

data.data_import

object

required

Show child attributes

data.data_import.state

string

required

State of the data import

data.data_import.import_check_errors

string

required

Errors encountered during the import check

data.data_import.started_at

string

required

When the import started

data.data_import.finished_at

string

required

When the import finished

data.data_import.data_source

object

required

Show child attributes

data.data_import.data_source.hostname

string

required

Hostname of the data source

data.data_import.data_source.port

integer

required

Port of the data source

data.data_import.data_source.database

string

required

Database name of the data source

data.region

object

required

Show child attributes

data.region.id

string

required

The ID of the region

data.region.provider

string

required

Provider for the region (ex. AWS)

data.region.enabled

boolean

required

Whether or not the region is currently active

data.region.public_ip_addresses

string[]

required

Public IP addresses for the region

data.region.display_name

string

required

Name of the region

data.region.location

string

required

Location of the region

data.region.slug

string

required

The slug of the region

data.region.current_default

boolean

required

True if the region is the default for new branch creation

data.html_url

string

required

The URL to see this database's branches in the web UI

data.name

string

required

Name of the database

data.state

enum<string>

required

State of the database

Available options:

pending,

importing,

sleep_in_progress,

sleeping,

awakening,

import_ready,

ready

data.sharded

boolean

required

If the database is sharded

data.default_branch_shard_count

integer

required

Number of shards in the default branch

data.default_branch_read_only_regions_count

integer

required

Number of read only regions in the default branch

data.default_branch_table_count

integer

required

Number of tables in the default branch schema

data.default_branch

string

required

The default branch for the database

data.require_approval_for_deploy

boolean

required

Whether an approval is required to deploy schema changes to this database

data.resizing

boolean

required

True if a branch is currently resizing

data.resize_queued

boolean

required

True if a branch has a queued resize request

data.allow_data_branching

boolean

required

Whether seeding branches with data is enabled for all branches

data.foreign_keys_enabled

boolean

required

Whether foreign key constraints are enabled

data.automatic_migrations

boolean

required

Whether to automatically manage Rails migrations during deploy requests

data.restrict_branch_region

boolean

required

Whether to restrict branch creation to one region

data.insights_raw_queries

boolean

required

Whether raw SQL queries are collected

data.plan

string

required

The database plan

data.insights_enabled

boolean

required

True if query insights is enabled for the database

data.production_branch_web_console

boolean

required

Whether web console is enabled for production branches

data.migration_table_name

string

required

Table name to use for copying schema migration data

data.migration_framework

string

required

Framework used for applying migrations

data.created_at

string

required

When the database was created

data.updated_at

string

required

When the database was last updated

data.schema_last_updated_at

string

required

When the default branch schema was last changed.

data.kind

enum<string>

required

The kind of database

Available options:

mysql,

postgresql

Delete a branch

Create a database

⌘I

Introduction

Webhooks in PlanetScale

Authentication

General API endpoints

Postgres API endpoints

Vitess API endpoints

List databases

Authorization

Authorizations

Path Parameters

Query Parameters

Response