Create an Astra DB Serverless database

Astra DB Serverless is a fully managed serverless database-as-a-service (DBaaS) that is powered by Apache Cassandra®, an open-source NoSQL distributed database.

Astra DB Serverless offers two types of serverless databases:

Serverless (vector) databases

Designed for vector search applications, such as Generative AI (GenAI) and semantic search, with support for non-vector use cases. You can store vectors alongside non-vector data or create collections and tables exclusively for non-vector data. You can load vectors directly with your data or automatically generate vector embeddings with vectorize.

Use Serverless (vector) databases for Retrieval Augmented Generation (RAG) applications, such as chatbots, agents, support bots, sentiment analysis, personalization, and multi-media search.

Serverless (non-vector) databases

Designed for generic applications, such as content management, user authentication, and transactional applications.

For more information, see About Astra DB Serverless and What are vector databases?.

Prerequisites

If you plan to bring your own encryption keys, you must create and register your customer keys before creating databases.

You need a role with the Create DB permission, such as the Organization Administrator or Database Administrator role. To create databases programmatically, you need an application token with an appropriately scoped role.

Create a Serverless (vector) database

  • Astra Portal

  • DevOps API

  • Data API clients

  • Astra CLI

  1. In the Astra Portal, click Create database.

  2. Click Serverless (vector).

  3. Enter a meaningful, human-readable database name.

    You cannot change the database name after you create the database.

    Database names must follow these rules:

    • Must start and end with a letter or number

    • Can contain letters, numbers, and the special characters & + - _ ( ) < > . , @

    • Cannot exceed 50 characters

  4. Select a cloud provider and region to host your database.

    On the Free plan, you can access a limited set of supported regions. To access Locked regions, you must upgrade your subscription plan.

    To minimize latency in production databases, select a region that is close to your application’s users.

    For multi-region availability, you can add more regions after you create the database.

  5. If applicable to your Astra organization, you can select or create a PCU group for the database.

  6. Click Create database.

    Wait for your database to initialize and reach Active status. This can take several minutes.

You can use the DevOps API to create Astra DB Serverless databases programmatically.

The following example uses the DevOps API to create a Serverless (vector) database:

curl -sS -L -X POST "https://api.astra.datastax.com/v2/databases" \
--header "Authorization: Bearer APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
  "name": "DATABASE_NAME",
  "keyspace": "",
  "cloudProvider": "CLOUD_PROVIDER",
  "region": "REGION",
  "dbType": "vector",
  "tier": "serverless",
  "capacityUnits": 1,
  "pcuGroupUUID": "PCU_GROUP_ID"
}'

Replace the following:

  • APPLICATION_TOKEN: An application token with a role that has permission to create databases.

  • DATABASE_NAME: A meaningful, human-readable database name.

    You cannot change the database name after you create the database.

    Database names must follow these rules:

    • Must start and end with a letter or number

    • Can contain letters, numbers, and the special characters & + - _ ( ) < > . , @

    • Cannot exceed 50 characters

  • CLOUD_PROVIDER: One of 'aws', 'gcp', or 'azure'.

  • REGION: An unlocked region that supports Serverless (vector) databases.

    On the Free plan, you can access a limited set of supported regions. To access Locked regions, you must upgrade your subscription plan.

    To minimize latency in production databases, select a region that is close to your application’s users.

    For multi-region availability, you can add more regions after you create the database.

    You can use the DevOps API or a Data API client to list available regions. For more information, see the following:

  • PCU_GROUP_ID: If your organization uses PCU groups, you can provide a pcuGroupUUID in your DevOps API request body to assign the database to the specified PCU group. The specified PCU group must have the same cloudProvider and region as the database.

    The capacityUnits field must be 1 for Astra DB Serverless databases. This setting is unrelated to PCU group capacity.

    To create the database without assigning it to a PCU group, omit the pcuGroupUUID parameter.

Set the remaining parameters as shown in the example:

  • keyspace takes an empty string ("") to use the default name default_keyspace.

  • dbType must be vector.

  • tier must be serverless.

  • capacityUnits must be 1.

For more information, see Create a database.

You can use the Data API clients to create databases programmatically. For more information and examples, see the Create a database.

The Data API clients don’t support PCU group assignment with database creation. To add a database to a PCU group during database creation, you must use the DevOps API or Astra Portal to create the database.

You can use the Astra CLI astra db create command to create Astra DB Serverless databases.

Once your database is active, you can create collections and tables, insert data, and connect to your database.

Create a Serverless (non-vector) database

  • Astra Portal

  • DevOps API

  • Data API clients

  • Astra CLI

  1. In the Astra Portal, click Create database.

  2. Click Serverless (non-vector).

  3. Enter a meaningful, human-readable database name.

    You cannot change the database name after you create the database.

    Database names must follow these rules:

    • Must start and end with a letter or number

    • Can contain letters, numbers, and the special characters & + - _ ( ) < > . , @

    • Cannot exceed 50 characters

  4. Enter a name for the database’s first keyspace.

    Keyspace names must follow these rules:

    • Must start with a letter or number

    • Can contain letters, numbers, and underscores

    • Cannot exceed 48 characters.

    • Cannot be the reserved words dse or system

    • Must be unique within the database

  5. Select a cloud provider and region to host your database.

    On the Free plan, you can access a limited set of supported regions. To access Locked regions, you must upgrade your subscription plan.

    To minimize latency in production databases, select a region that is close to your application’s users.

    For multi-region availability, you can add more regions after you create the database.

  6. If applicable to your organization, you can select or create a PCU group for the database.

  7. Click Create database.

    Wait for your database to initialize and reach Active status. This can take several minutes.

You can use the DevOps API to create Astra DB Serverless databases programmatically.

The following example uses the DevOps API to create a Serverless (non-vector) database:

curl -sS -L -X POST "https://api.astra.datastax.com/v2/databases" \
--header "Authorization: Bearer APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
  "name": "DATABASE_NAME",
  "keyspace": "KEYSPACE_NAME",
  "cloudProvider": "CLOUD_PROVIDER",
  "region": "REGION",
  "tier": "serverless",
  "capacityUnits": 1,
  "pcuGroupUUID": "PCU_GROUP_ID"
}'

Replace the following:

  • APPLICATION_TOKEN: An application token with a role that has permission to create databases.

  • DATABASE_NAME: A meaningful, human-readable database name.

    You cannot change the database name after you create the database.

    Database names must follow these rules:

    • Must start and end with a letter or number

    • Can contain letters, numbers, and the special characters & + - _ ( ) < > . , @

    • Cannot exceed 50 characters

  • KEYSPACE_NAME: A name for the database’s first keyspace.

    Keyspace names must follow these rules:

    • Must start with a letter or number

    • Can contain letters, numbers, and underscores

    • Cannot exceed 48 characters.

    • Cannot be the reserved words dse or system

    • Must be unique within the database

  • CLOUD_PROVIDER: One of 'aws', 'gcp', or 'azure'.

  • REGION: An unlocked region that supports Serverless (non-vector) databases.

    On the Free plan, you can access a limited set of supported regions. To access Locked regions, you must upgrade your subscription plan.

    To minimize latency in production databases, select a region that is close to your application’s users.

    For multi-region availability, you can add more regions after you create the database.

    You can use the DevOps API or a Data API client to list available regions. For more information, see the following:

  • PCU_GROUP_ID: If your organization uses PCU groups, you can provide a pcuGroupUUID in your DevOps API request body to assign the database to the specified PCU group. The specified PCU group must have the same cloudProvider and region as the database.

    The capacityUnits field must be 1 for Astra DB Serverless databases. This setting is unrelated to PCU group capacity.

    To create the database without assigning it to a PCU group, omit the pcuGroupUUID parameter.

Set the remaining parameters as shown in the example:

  • tier must be serverless.

  • capacityUnits must be 1.

For more information, see Create a database.

You can use the Data API clients to create databases programmatically. For more information and examples, see the Create a database.

The Data API clients don’t support PCU group assignment with database creation. To add a database to a PCU group during database creation, you must use the DevOps API or Astra Portal to create the database.

You can use the Astra CLI astra db create command to create Astra DB Serverless databases.

Once your database is active, you can create tables, insert data, and connect to your database.

Get database details

After you create an Astra DB Serverless database, you can get information about it, such as the database name, ID, status, and regions.

At minimum, you can access databases that you create. Your role determines whether you have access to databases created by other users in your Astra organization.

Get database details in the Astra Portal

The Astra Portal dashboard shows a summary of your organization’s Astra DB Serverless databases. To inspect a specific database, click the database’s name.

Get details for one database with the DevOps API

To get information about a specific database, use GET /v2/databases/DATABASE_ID:

curl -sS -L -X GET "https://api.astra.datastax.com/v2/databases/DATABASE_ID" \
--header "Authorization: Bearer APPLICATION_TOKEN" \
--header "Content-Type: application/json"

Replace the following:

A successful request returns 200 Created and an object containing database information.

Get details for all databases in an organization with the DevOps API

To get all databases in an organization, use GET /v2/databases:

curl -sS -L -X GET "https://api.astra.datastax.com/v2/databases" \
--header "Authorization: Bearer APPLICATION_TOKEN" \
--header "Content-Type: application/json"

The organization to query is inferred from the application token.

The application token must have a role that is permitted to view all databases in the organization, such as the Organization Administrator role.

A successful request returns 200 Created and an array of objects containing information about each database in the organization.

Get database details with the Astra CLI

The Astra CLI provides several commands to get information about databases, including astra db get and more specific commands like astra db list-regions.

Get your database ID

Get a database ID in the Astra Portal

In the Astra Portal, you can see a list of all of your databases along with their IDs.

Alternatively, click the name of a specific database to get the database ID from the database details page or in the page URL, such as astra.datastax.com/org/ORGANIZATION_ID/database/DATABASE_ID/.

Get a database ID with the DevOps API

You can use the DevOps API List databases endpoint to get all database IDs at once:

curl -sS -L -X GET "https://api.astra.datastax.com/v2/databases" \
--header "Authorization: Bearer APPLICATION_TOKEN" \
--header "Content-Type: application/json"

Make sure the application token has View DB permission for all relevant databases. For example, the Organization Administrator role can view all databases within an Astra organization. If the supplied token doesn’t have permission to view a particular database, the response won’t include any information for that database.

A successful response contains an array of database objects. In each object, the id field contains the database ID. The following example is truncated for clarity.

Result
[
  {
    "id": "FIRST_DATABASE_ID",
    "orgId": "organizations/ORGANIZATION_ID",
    "ownerId": "users/ADMIN_USER_ID",
    "info": { ... },
    "creationTime": "2012-11-01T22:08:41+00:00",
    "terminationTime": "2019-11-01T22:08:41+00:00",
    "status": "ACTIVE",
    "storage": { ... },
    "availableActions": [ ... ],
    ...
  },
  {
    "id": "SECOND_DATABASE_ID",
    "orgId": "organizations/ORGANIZATION_ID",
    "ownerId": "users/ADMIN_USER_ID",
    "info": { ... },
    "creationTime": "2012-11-01T22:08:41+00:00",
    "terminationTime": "2019-11-01T22:08:41+00:00",
    "status": "ACTIVE",
    "storage": { ... },
    "availableActions": [ ... ],
    ...
  }
]
Get a database ID with the Astra CLI

See astra db get.

Get a database ID with the Data API clients

See Find all databases.

Get a database region ID (datacenter ID)

Datacenter IDs are region-specific database IDs for multi-region databases.

Get datacenter IDs in the Astra Portal

  1. In the Astra Portal, click the name of the database that you want to inspect.

  2. On the Overview tab, in the Regions section, you can find the regions where the database is deployed along with each region’s Datacenter ID.

    For single-region databases, there is only one Datacenter ID, which is the database ID suffixed by -1. Multi-region databases have a Datacenter ID for each region.

Get datacenter IDs with the DevOps API

You can use the DevOps API to list all regions for a specific database:

curl -sS -L -X GET "https://api.astra.datastax.com/v2/databases/DATABASE_ID/datacenters" \
--header "Authorization: Bearer APPLICATION_TOKEN" \
--header "Content-Type: application/json"

The response includes information about the database, including datacenter ID (id), region, database type, status, and various access URLs. For multi-region databases, the response includes an object for each region where the database is deployed.

The datacenter ID (id) is the database ID with a numerical suffix. The -1 suffix indicates the primary region, and secondary regions are numbered in the order they were added to the database.

Result
[
  {
    "id": "1234-5678-91011121-3141-1",
    "name": "dc-1234-5678-91011121-3141",
    "tier": "serverless",
    "status": "ACTIVE",
    "cloudProvider": "GCP",
    "region": "us-east1",
    "regionZone": "na",
    "regionClassification": "standard",
    "capacityUnits": 1,
    "grafanaUrl": "http://path-to-grafana:port",
    "cqlshUrl": "http://path-to-cqlsh:port/cqlsh",
    "dataEndpointUrl": "http://path-to-dataendpoint:port/api/rest",
    "secureBundleUrl": "http://s3-signed-bundle-url",
    "secureBundleInternalUrl": "http://s3-signed-internal-bundle-url",
    "secureBundleMigrationProxyUrl": "http://s3-signed-proxy-bundle-url",
    "secureBundleMigrationProxyInternalUrl": "http://s3-signed-proxy-internal-bundle-url"
  }
]
Get datacenter IDs with the Astra CLI

See astra db get or astra db list-regions.

Get a database Data API endpoint

Get a Data API endpoint in the Astra Portal

In the Astra Portal, click the name of the Serverless (vector) database that you want to connect to. The Data API endpoint for your database is listed under the Database Details section.

Get a Data API endpoint with the Astra CLI

See astra db endpoints data-api.

Troubleshoot database limit error

If you are unable to create a database due to reaching the database limit, check your organization’s subscription plan. Organizations on the Free plan cannot have more than five databases.

See also

Was this helpful?

Give Feedback

How can we improve the documentation?

© Copyright IBM Corporation 2026 | Privacy policy | Terms of use |  Manage Privacy Choices

Apache, Apache Cassandra, Cassandra, Apache Tomcat, Tomcat, Apache Lucene, Apache Solr, Apache Hadoop, Hadoop, Apache Pulsar, Pulsar, Apache Spark, Spark, Apache TinkerPop, TinkerPop, Apache Kafka and Kafka are either registered trademarks or trademarks of the Apache Software Foundation or its subsidiaries in Canada, the United States and/or other countries. Kubernetes is the registered trademark of the Linux Foundation.

General Inquiries: Contact IBM