Api key (http_api_key)
Send an authentication token in the
Authorization
header
to authenticate with the API.
https://api.elastic-cloud.com/api/v1
This RESTful API enables you to perform most of the operations available in the UI console through API calls.
You can create an API key to quickly and easily authenticate, then use the API to create and manage deployments, configure remote clusters, set up traffic filters, manage extensions, and much more.
Access the API from its base URL at api.elastic-cloud.com
.
For details about creating an API key, refer to Access and authentication.
To manage your serverless projects, use the Elastic Cloud Serverless API.
This documentation is derived from https://api.elastic-cloud.com/api/v1/api-docs-user/swagger.json. It is provided under license Attribution-NonCommercial-NoDerivatives 4.0 International.
This is version 1
of this API documentation.
Last update on Dec 12, 2024.
Send an authentication token in the
Authorization
header
to authenticate with the API.
The Elasticsearch Service API is built on REST. This means that:
RESTful API calls are stateless. Every request that you make happens in isolation from other calls and must include all the information necessary for Elasticsearch Service to fulfill the request. API requests return JSON output, which is a format that is machine-readable and works well for automation.
Calls to API endpoints require different request methods, depending on what they do. You use these four request methods to communicate with the Elasticsearch Service RESTful API:
API calls are rate limited in a timing window. The current remaining available calls quota is available through the following header fields, included in each API call response:
x-ratelimit-interval
- The time duration for the quota calculation.x-ratelimit-remaining
- The remaining number of API calls available.x-ratelimit-limit
- The total number of calls available in the duration x-ratelimit-interval
.Retrieve and update the current Elasticsearch Service account.
curl \
-X GET https://api.elastic-cloud.com/api/v1/account
{
"id": "string",
"trust": {
"trust_all": true
}
}
# Headers
x-cloud-error-codes: accounts.not_found
# Payload
{
"errors": [
{
"code": "string",
"message": "string",
"fields": [
"string"
]
}
]
}
curl \
-X PUT https://api.elastic-cloud.com/api/v1/account \
-d '{"trust":{"trust_all":true}}'
{
"trust": {
"trust_all": true
}
}
{
"id": "string",
"trust": {
"trust_all": true
}
}
# Headers
x-cloud-error-codes: accounts.not_found
# Payload
{
"errors": [
{
"code": "string",
"message": "string",
"fields": [
"string"
]
}
]
}
All changes in the specified object are applied to the current account according to the JSON Merge Patch processing rules. Omitting existing fields causes the same values to be reapplied. Specifying a null
value reverts the field to the default value, or removes the field when no default value exists.
curl \
-X PATCH https://api.elastic-cloud.com/api/v1/account \
-d '"string"'
string
{
"id": "string",
"trust": {
"trust_all": true
}
}
# Headers
x-cloud-error-codes: accounts.not_found
# Payload
{
"errors": [
{
"code": "string",
"message": "string",
"fields": [
"string"
]
}
]
}
Manage your Elasticsearch Service API keys.
Retrieves the metadata for all of the API keys that the user generated.
curl \
-X GET https://api.elastic-cloud.com/api/v1/users/auth/keys
{
"keys": [
{
"id": "string",
"user_id": "string",
"organization_id": "string",
"description": "string",
"key": "string",
"creation_date": "2025-05-04T09:42:00+00:00",
"expiration_date": "2025-05-04T09:42:00+00:00",
"role_assignments": {
"platform": [
{
"role_id": "string"
}
],
"organization": [
{
"role_id": "string",
"organization_id": "string"
}
],
"deployment": [
{
"role_id": "string",
"organization_id": "string",
"all": true,
"deployment_ids": [
"string"
],
"application_roles": [
"string"
]
}
],
"project": {
"elasticsearch": [
{
"role_id": "string",
"organization_id": "string",
"all": true,
"project_ids": [
"string"
],
"application_roles": [
"string"
]
}
],
"observability": [
{
"role_id": "string",
"organization_id": "string",
"all": true,
"project_ids": [
"string"
],
"application_roles": [
"string"
]
}
],
"security": [
{
"role_id": "string",
"organization_id": "string",
"all": true,
"project_ids": [
"string"
],
"application_roles": [
"string"
]
}
]
}
}
}
]
}
The request to create the API key
API key description. Useful if there are multiple keys
The optional expiration for the API key, provided as a duration (ex: '1d', '3h')
The roles that will be assigned to users once they accept the invitation. Currently unavailable in self-hosted ECE.
Additional properties are allowed.
curl \
-X POST https://api.elastic-cloud.com/api/v1/users/auth/keys \
-d '{"description":"string","expiration":"string","role_assignments":{"platform":[{"role_id":"string"}],"organization":[{"role_id":"string","organization_id":"string"}],"deployment":[{"role_id":"string","organization_id":"string","all":true,"deployment_ids":["string"],"application_roles":["string"]}],"project":{"elasticsearch":[{"role_id":"string","organization_id":"string","all":true,"project_ids":["string"],"application_roles":["string"]}],"observability":[{"role_id":"string","organization_id":"string","all":true,"project_ids":["string"],"application_roles":["string"]}],"security":[{"role_id":"string","organization_id":"string","all":true,"project_ids":["string"],"application_roles":["string"]}]}}}'
{
"description": "string",
"expiration": "string",
"role_assignments": {
"platform": [
{
"role_id": "string"
}
],
"organization": [
{
"role_id": "string",
"organization_id": "string"
}
],
"deployment": [
{
"role_id": "string",
"organization_id": "string",
"all": true,
"deployment_ids": [
"string"
],
"application_roles": [
"string"
]
}
],
"project": {
"elasticsearch": [
{
"role_id": "string",
"organization_id": "string",
"all": true,
"project_ids": [
"string"
],
"application_roles": [
"string"
]
}
],
"observability": [
{
"role_id": "string",
"organization_id": "string",
"all": true,
"project_ids": [
"string"
],
"application_roles": [
"string"
]
}
],
"security": [
{
"role_id": "string",
"organization_id": "string",
"all": true,
"project_ids": [
"string"
],
"application_roles": [
"string"
]
}
]
}
}
}
{
"id": "string",
"user_id": "string",
"organization_id": "string",
"description": "string",
"key": "string",
"creation_date": "2025-05-04T09:42:00+00:00",
"expiration_date": "2025-05-04T09:42:00+00:00",
"role_assignments": {
"platform": [
{
"role_id": "string"
}
],
"organization": [
{
"role_id": "string",
"organization_id": "string"
}
],
"deployment": [
{
"role_id": "string",
"organization_id": "string",
"all": true,
"deployment_ids": [
"string"
],
"application_roles": [
"string"
]
}
],
"project": {
"elasticsearch": [
{
"role_id": "string",
"organization_id": "string",
"all": true,
"project_ids": [
"string"
],
"application_roles": [
"string"
]
}
],
"observability": [
{
"role_id": "string",
"organization_id": "string",
"all": true,
"project_ids": [
"string"
],
"application_roles": [
"string"
]
}
],
"security": [
{
"role_id": "string",
"organization_id": "string",
"all": true,
"project_ids": [
"string"
],
"application_roles": [
"string"
]
}
]
}
}
}
# Headers
x-cloud-error-codes: api_keys.invalid_input
# Payload
{
"errors": [
{
"code": "string",
"message": "string",
"fields": [
"string"
]
}
]
}
curl \
-X DELETE https://api.elastic-cloud.com/api/v1/users/auth/keys \
-d '{"keys":["string"]}'
{
"keys": [
"string"
]
}
{}
The API Key ID.
curl \
-X GET https://api.elastic-cloud.com/api/v1/users/auth/keys/{api_key_id}
{
"id": "string",
"user_id": "string",
"organization_id": "string",
"description": "string",
"key": "string",
"creation_date": "2025-05-04T09:42:00+00:00",
"expiration_date": "2025-05-04T09:42:00+00:00",
"role_assignments": {
"platform": [
{
"role_id": "string"
}
],
"organization": [
{
"role_id": "string",
"organization_id": "string"
}
],
"deployment": [
{
"role_id": "string",
"organization_id": "string",
"all": true,
"deployment_ids": [
"string"
],
"application_roles": [
"string"
]
}
],
"project": {
"elasticsearch": [
{
"role_id": "string",
"organization_id": "string",
"all": true,
"project_ids": [
"string"
],
"application_roles": [
"string"
]
}
],
"observability": [
{
"role_id": "string",
"organization_id": "string",
"all": true,
"project_ids": [
"string"
],
"application_roles": [
"string"
]
}
],
"security": [
{
"role_id": "string",
"organization_id": "string",
"all": true,
"project_ids": [
"string"
],
"application_roles": [
"string"
]
}
]
}
}
}
# Headers
x-cloud-error-codes: api_keys.key_not_found
# Payload
{
"errors": [
{
"code": "string",
"message": "string",
"fields": [
"string"
]
}
]
}
The API Key ID.
curl \
-X DELETE https://api.elastic-cloud.com/api/v1/users/auth/keys/{api_key_id}
{}
# Headers
x-cloud-error-codes: api_keys.key_not_found
# Payload
{
"errors": [
{
"code": "string",
"message": "string",
"fields": [
"string"
]
}
]
}
Get an overview of your costs by organization ID.
EXPERIMENTAL (it may change in future versions): Retrieves an overview of the costs by organization ID.
Identifier for the organization
Top-level cost overview for the organization
The specified date range is invalid. (code: costs.invalid_date_range
)
The current user does not have access to the requested organization. (code: organization.invalid_access
)
Organization not found. (code: organization.not_found
)
An error occurred when fetching an overview of the costs for the organization. (code: billing_service.failed_request
)
curl \
-X GET https://api.elastic-cloud.com/api/v1/billing/costs/{organization_id}
{
"costs": {
"total": 42.0,
"dimensions": [
{
"type": "capacity",
"cost": 42.0
}
]
},
"trials": 42.0,
"hourly_rate": 42.0,
"balance": {
"available": 42.0,
"remaining": 42.0,
"line_items": [
{
"id": "string",
"ecu_quantity": 42.0,
"ecu_balance": 42.0,
"start": "2025-05-04T09:42:00+00:00",
"end": "2025-05-04T09:42:00+00:00"
}
]
}
}
# Headers
x-cloud-error-codes: costs.invalid_date_range
# Payload
{
"errors": [
{
"code": "string",
"message": "string",
"fields": [
"string"
]
}
]
}
# Headers
x-cloud-error-codes: organization.invalid_access
# Payload
{
"errors": [
{
"code": "string",
"message": "string",
"fields": [
"string"
]
}
]
}
# Headers
x-cloud-error-codes: organization.not_found
# Payload
{
"errors": [
{
"code": "string",
"message": "string",
"fields": [
"string"
]
}
]
}
# Headers
x-cloud-error-codes: billing_service.failed_request
# Payload
{
"errors": [
{
"code": "string",
"message": "string",
"fields": [
"string"
]
}
]
}
EXPERIMENTAL (it may change in future versions): Retrieves the usage charts for the organization.
Identifier for the organization
A datetime for the beginning of the desired range for which to fetch costs. Defaults to start of current month.
A datetime for the end of the desired range for which to fetch costs. Defaults to the current date.
The desired bucketing strategy for the charts. Defaults to daily
.
Values are daily
or monthly
. Default value is daily
.
The usage charts of an organization.
The specified date range is invalid. (code: costs.invalid_date_range
)
The current user does not have access to the requested organization. (code: organization.invalid_access
)
Organization not found. (code: organization.not_found
)
Too many requests. (code: billing_service.rate_limited
)
Error fetching the itemized costs for the organization. (code: billing_service.failed_request
)
curl \
-X GET https://api.elastic-cloud.com/api/v1/billing/costs/{organization_id}/charts
{
"data": [
{
"timestamp": 42,
"values": [
{
"id": "string",
"name": "string",
"value": 42.0
}
]
}
]
}
# Headers
x-cloud-error-codes: costs.invalid_date_range
# Payload
{
"errors": [
{
"code": "string",
"message": "string",
"fields": [
"string"
]
}
]
}
# Headers
x-cloud-error-codes: organization.invalid_access
# Payload
{
"errors": [
{
"code": "string",
"message": "string",
"fields": [
"string"
]
}
]
}
# Headers
x-cloud-error-codes: organization.not_found
# Payload
{
"errors": [
{
"code": "string",
"message": "string",
"fields": [
"string"
]
}
]
}
# Headers
x-cloud-error-codes: billing_service.rate_limited
# Payload
{
"errors": [
{
"code": "string",
"message": "string",
"fields": [
"string"
]
}
]
}
# Headers
x-cloud-error-codes: billing_service.failed_request
# Payload
{
"errors": [
{
"code": "string",
"message": "string",
"fields": [
"string"
]
}
]
}
EXPERIMENTAL (it may change in future versions): Retrieves the costs associated with all deployments for the organization.
Identifier for the organization
The costs associated to a set of products
Invalid date range specified. (code: costs.invalid_date_range
)
The current user does not have access to the requested organization. (code: organization.invalid_access
)
Organization not found. (code: organization.not_found
)
An error occurred when fetching the costs associated with all deployments for the organization. (code: billing_service.failed_request
)
curl \
-X GET https://api.elastic-cloud.com/api/v1/billing/costs/{organization_id}/deployments \
-H "Accept: string"
{
"total_cost": 42.0,
"deployments": [
{
"deployment_id": "string",
"deployment_name": "string",
"costs": {
"total": 42.0,
"dimensions": [
{
"type": "capacity",
"cost": 42.0
}
]
},
"hourly_rate": 42.0,
"period": {
"start": "2025-05-04T09:42:00+00:00",
"end": "2025-05-04T09:42:00+00:00"
}
}
]
}
# Headers
x-cloud-error-codes: costs.invalid_date_range
# Payload
{
"errors": [
{
"code": "string",
"message": "string",
"fields": [
"string"
]
}
]
}
# Headers
x-cloud-error-codes: organization.invalid_access
# Payload
{
"errors": [
{
"code": "string",
"message": "string",
"fields": [
"string"
]
}
]
}
# Headers
x-cloud-error-codes: organization.not_found
# Payload
{
"errors": [
{
"code": "string",
"message": "string",
"fields": [
"string"
]
}
]
}
# Headers
x-cloud-error-codes: billing_service.failed_request
# Payload
{
"errors": [
{
"code": "string",
"message": "string",
"fields": [
"string"
]
}
]
}
EXPERIMENTAL (it may change in future versions): Retrieves the usage charts for the given deployment.
Identifier for the organization
Id of a Deployment
A datetime for the beginning of the desired range for which to fetch costs. Defaults to start of current month.
A datetime for the end of the desired range for which to fetch costs. Defaults to the current date.
The desired bucketing strategy for the charts. Defaults to daily
.
Values are daily
or monthly
. Default value is daily
.
The usage charts of a deployment.
The specified date range is invalid. (code: costs.invalid_date_range
)
The current user does not have access to the requested organization. (code: organization.invalid_access
)
Organization not found. (code: organization.not_found
)
Too many requests. (code: billing_service.rate_limited
)
Error fetching the itemized costs for the organization. (code: billing_service.failed_request
)
curl \
-X GET https://api.elastic-cloud.com/api/v1/billing/costs/{organization_id}/deployments/{deployment_id}/charts
{
"data": [
{
"timestamp": 42,
"values": [
{
"id": "string",
"name": "string",
"value": 42.0
}
]
}
]
}
# Headers
x-cloud-error-codes: costs.invalid_date_range
# Payload
{
"errors": [
{
"code": "string",
"message": "string",
"fields": [
"string"
]
}
]
}
# Headers
x-cloud-error-codes: organization.invalid_access
# Payload
{
"errors": [
{
"code": "string",
"message": "string",
"fields": [
"string"
]
}
]
}
# Headers
x-cloud-error-codes: organization.not_found
# Payload
{
"errors": [
{
"code": "string",
"message": "string",
"fields": [
"string"
]
}
]
}
# Headers
x-cloud-error-codes: billing_service.rate_limited
# Payload
{
"errors": [
{
"code": "string",
"message": "string",
"fields": [
"string"
]
}
]
}
# Headers
x-cloud-error-codes: billing_service.failed_request
# Payload
{
"errors": [
{
"code": "string",
"message": "string",
"fields": [
"string"
]
}
]
}
EXPERIMENTAL (it may change in future versions): Retrieves the itemized costs for the given deployment.
Determines the response body format. Can be either application/json or text/csv.
Identifier for the organization
Id of a Deployment
The costs associated to a set items billed for a single deployment.
The specified date range is invalid. (code: costs.invalid_date_range
)
The current user does not have access to the requested organization. (code: organization.invalid_access
)
organization.not_found
)billing_service.es_cluster_id_not_found
)An error occurred when fetching the itemized costs for the given deployment of the organization. (code: billing_service.failed_request
)
curl \
-X GET https://api.elastic-cloud.com/api/v1/billing/costs/{organization_id}/deployments/{deployment_id}/items \
-H "Accept: string"
{
"costs": {
"total": 42.0,
"dimensions": [
{
"type": "capacity",
"cost": 42.0
}
]
},
"data_transfer_and_storage": [
{
"cost": 42.0,
"name": "string",
"quantity": {
"value": 42,
"formatted_value": "string"
},
"rate": {
"value": 42.0,
"formatted_value": "string"
},
"sku": "string",
"type": "string"
}
],
"resources": [
{
"hours": 42,
"instance_count": 42,
"period": {
"start": "2025-05-04T09:42:00+00:00",
"end": "2025-05-04T09:42:00+00:00"
},
"kind": "elasticsearch",
"price": 42.0,
"price_per_hour": 42.0,
"name": "string",
"sku": "string"
}
]
}
# Headers
x-cloud-error-codes: costs.invalid_date_range
# Payload
{
"errors": [
{
"code": "string",
"message": "string",
"fields": [
"string"
]
}
]
}
# Headers
x-cloud-error-codes: organization.invalid_access
# Payload
{
"errors": [
{
"code": "string",
"message": "string",
"fields": [
"string"
]
}
]
}
# Headers
x-cloud-error-codes: organization.not_found
# Payload
{
"errors": [
{
"code": "string",
"message": "string",
"fields": [
"string"
]
}
]
}
# Headers
x-cloud-error-codes: billing_service.failed_request
# Payload
{
"errors": [
{
"code": "string",
"message": "string",
"fields": [
"string"
]
}
]
}
EXPERIMENTAL (it may change in future versions): Retrieves the itemized costs for the organization.
Identifier for the organization
The costs associated to a set of items
The specified date range is invalid. (code: costs.invalid_date_range
)
The current user does not have access to the requested organization. (code: organization.invalid_access
)
Organization not found. (code: organization.not_found
)
Error fetching the itemized costs for the organization. (code: billing_service.failed_request
)
curl \
-X GET https://api.elastic-cloud.com/api/v1/billing/costs/{organization_id}/items
{
"costs": {
"total": 42.0,
"dimensions": [
{
"type": "capacity",
"cost": 42.0
}
]
},
"data_transfer_and_storage": [
{
"cost": 42.0,
"name": "string",
"quantity": {
"value": 42,
"formatted_value": "string"
},
"rate": {
"value": 42.0,
"formatted_value": "string"
},
"sku": "string",
"type": "string"
}
],
"resources": [
{
"hours": 42,
"instance_count": 42,
"period": {
"start": "2025-05-04T09:42:00+00:00",
"end": "2025-05-04T09:42:00+00:00"
},
"kind": "elasticsearch",
"price": 42.0,
"price_per_hour": 42.0,
"name": "string",
"sku": "string"
}
]
}
# Headers
x-cloud-error-codes: costs.invalid_date_range
# Payload
{
"errors": [
{
"code": "string",
"message": "string",
"fields": [
"string"
]
}
]
}
# Headers
x-cloud-error-codes: organization.invalid_access
# Payload
{
"errors": [
{
"code": "string",
"message": "string",
"fields": [
"string"
]
}
]
}
# Headers
x-cloud-error-codes: organization.not_found
# Payload
{
"errors": [
{
"code": "string",
"message": "string",
"fields": [
"string"
]
}
]
}
# Headers
x-cloud-error-codes: billing_service.failed_request
# Payload
{
"errors": [
{
"code": "string",
"message": "string",
"fields": [
"string"
]
}
]
}
Manage APM routes and read-only mode on App Search resources. Perform CRUD operations and commands. Get information about the certificate authorities, resources, remote clusters, and upgrade assistant status in your deployments.