---
title: "find database by handle"
method: GET
path: "/find/database"
tags: ["Databases"]
---

# find database by handle

`GET /find/database`

## Request

- Base URL: `https://api.aptible.com`
- URL: `https://api.aptible.com/find/database`
- Auth: API key in header `Authorization`

Returns the database matching the specified handle.

## Query parameters

- `handle` string, required
- `environment` string
- `no_embed` boolean

## Headers

- `Prefer` 'no_sensitive_extras=true'

## Response `200`

successful

- Database
  - `id` integer, required
  - `handle` string, required
  - `type` string, required
  - `passphrase` string
  - `connection_url` string
  - `provisioned` boolean, required
  - `_type` string, required
  - `created_at` string, dateTime, required
  - `updated_at` string, dateTime, required
  - `status` string, required
  - `docker_repo` string, required
  - `port_mapping` array[], required
    - integer[]
  - `initial_disk_size` integer, required
  - `initial_container_size` integer, required
  - `current_kms_arn` string, required
  - `enable_backups` boolean, required
  - `pitr_bucket` string, required
  - `oldest_pitr_time` string, required
  - `enable_pitr` boolean, required
  - `pitr_status` 'unsupported' | 'supported' | 'pending_restart' | 'restricted', required
  - `_embedded` DatabaseEmbedded, required
    - `last_operation` Operation
      - `id` integer, required
      - `_type` string, required
      - `type` string, required
      - `status` string, required
      - `cancelled` boolean, required
      - `aborted` boolean, required
      - `git_ref` string, required
      - `docker_ref` string, required
      - `deploy_image_id` integer
      - `env` object
      - `container_size` integer, required
      - `container_count` integer, required
      - `disk_size` integer, required
      - `command` string, required
      - `handle` string, required
      - `created_at` string, dateTime, required
      - `updated_at` string, dateTime, required
      - `certificate` string, required
      - `private_key` string
      - `user_name` string, required
      - `user_email` string, required
      - `destination_region` string, required
      - `interactive` boolean, required
      - `instance_profile` string, required
      - `mount_point` string, required
      - `daily` integer, required
      - `monthly` integer, required
      - `yearly` integer, required
      - `pitr_days` integer, required
      - `make_copy` boolean, required
      - `keep_final` boolean, required
      - `enable_backups` boolean, required
      - `enable_pitr` boolean, required
      - `settings` object, required
      - `sensitive_settings` object
      - `_links` OperationLinks
        - `user` ListAccountsForStack200ResponseLinksStack
          - `href` string, uri
        - `resource` ListAccountsForStack200ResponseLinksStack
          - `href` string, uri
        - `account` ListAccountsForStack200ResponseLinksStack
          - `href` string, uri
        - `destination_account` ListAccountsForStack200ResponseLinksStack
          - `href` string, uri
        - `ssh_portal_connections` ListAccountsForStack200ResponseLinksStack
          - `href` string, uri
        - `ephemeral_sessions` ListAccountsForStack200ResponseLinksStack
          - `href` string, uri
        - `code_scan_result` ListAccountsForStack200ResponseLinksStack
          - `href` string, uri
        - `deploy_image` ListAccountsForStack200ResponseLinksStack
          - `href` string, uri
        - `service` ListAccountsForStack200ResponseLinksStack
          - `href` string, uri
        - `self` ListAccountsForStack200ResponseLinksStack
          - `href` string, uri
    - `disk` Disk
      - `id` integer, required
      - `handle` string, required
      - `ebs_volume_id` string, required
      - `ebs_volume_type` string, required
      - `filesystem` string, required
      - `passphrase` string
      - `key_bytes` integer, required
      - `size` integer, required
      - `provisioned_iops` integer, required
      - `host` string, required
      - `device` string, required
      - `attached` boolean, required
      - `_type` string, required
      - `created_at` string, dateTime, required
      - `updated_at` string, dateTime, required
      - `ec2_instance_id` string, required
      - `baseline_iops` integer, required
      - `availability_zone` string, required
      - `current_kms_arn` string, required
      - `_links` DiskLinks
        - `account` ListAccountsForStack200ResponseLinksStack
          - `href` string, uri
        - `database` ListAccountsForStack200ResponseLinksStack
          - `href` string, uri
        - `operations` ListAccountsForStack200ResponseLinksStack
          - `href` string, uri
        - `self` ListAccountsForStack200ResponseLinksStack
          - `href` string, uri
    - `database_credentials` DatabaseCredential[]
      - `id` integer, required
      - `_type` string, required
      - `created_at` string, dateTime, required
      - `updated_at` string, dateTime, required
      - `connection_url` string
      - `type` string, required
      - `default` boolean, required
      - `_links` DatabaseCredentialLinks
        - `database` ListAccountsForStack200ResponseLinksStack
          - `href` string, uri
        - `operations` ListAccountsForStack200ResponseLinksStack
          - `href` string, uri
        - `self` ListAccountsForStack200ResponseLinksStack
          - `href` string, uri
  - `_links` DatabaseLinks
    - `account` ListAccountsForStack200ResponseLinksStack
      - `href` string, uri
    - `database_image` ListAccountsForStack200ResponseLinksStack
      - `href` string, uri
    - `service` ListAccountsForStack200ResponseLinksStack
      - `href` string, uri
    - `disk` ListAccountsForStack200ResponseLinksStack
      - `href` string, uri
    - `initialize_from` ListAccountsForStack200ResponseLinksStack
      - `href` string, uri
    - `current_configuration` ListAccountsForStack200ResponseLinksStack
      - `href` string, uri
    - `dependents` ListAccountsForStack200ResponseLinksStack
      - `href` string, uri
    - `operations` ListAccountsForStack200ResponseLinksStack
      - `href` string, uri
    - `backups` ListAccountsForStack200ResponseLinksStack
      - `href` string, uri
    - `configurations` ListAccountsForStack200ResponseLinksStack
      - `href` string, uri
    - `database_credentials` ListAccountsForStack200ResponseLinksStack
      - `href` string, uri
    - `settings` ListAccountsForStack200ResponseLinksStack
      - `href` string, uri
    - `current_setting` ListAccountsForStack200ResponseLinksStack
      - `href` string, uri
    - `self` ListAccountsForStack200ResponseLinksStack
      - `href` string, uri

## Other responses

- `default`: Error response. Often a 4xx or 5xx status code

## Changes

- **2026-10-20** `ba72edfe0324`: 2 info
  - added the optional property `_embedded/last_operation/_links/deploy_image` to the response with the `200` status
  - added the optional property `_embedded/last_operation/deploy_image_id` to the response with the `200` status
- **2026-07-24** `1dc1e5b8c6eb`: 6 breaking, 2 info
  - the response property `_embedded/database_credentials/items/connection_url` became optional for the status `200`
  - the response property `_embedded/last_operation/env` became optional for the status `200`
  - the response property `_embedded/last_operation/private_key` became optional for the status `200`
  - the response property `_embedded/last_operation/sensitive_settings` became optional for the status `200`
  - …4 more
- **2026-07-15** `5c71f4c63067`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/aptible/apis/aptible-api-v1/changes/find/database/get.md)

---

[API](https://skmtc.dev/aptible/apis/aptible-api-v1.md) - [All operations](https://skmtc.dev/aptible/apis/aptible-api-v1/llms.txt) - [OpenAPI document](https://skmtc.dev/aptible/apis/aptible-api-v1/revisions/a21f6b1bc6fe?raw)