Elastic Cloud API
1

Base URL
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.

Documentation source and versions

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.

Authentication

Api key (http_api_key)

Send an authentication token in the Authorization header to authenticate with the API.

Principles

The Elasticsearch Service API is built on REST. This means that:

  • URLs are based on resource IDs.
  • JSON is the data interchange format.
  • Standard HTTP response codes and verbs are used.

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:

  • To fetch a resource: GET
  • To create a new resource: POST
  • To update an existing resource: PUT or PATCH
  • To delete a resource: DELETE

Rate limiting

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.

Accounts

Retrieve and update the current Elasticsearch Service account.

Fetch current account information

GET /account

Fetch current account information.

Responses

  • Account fetched successfully

    Hide response attributes Show response attributes object
    • id string Required

      The account's identifier

    • trust object

      Settings related to the level of trust of the clusters in this account

      Additional properties are allowed.

      Hide trust attribute Show trust attribute object
      • trust_all boolean Required

        If true, all clusters in this account will by default trust all other clusters in the same account

  • Account not found. (code: accounts.not_found)

    Hide headers attribute Show headers attribute
    Hide response attribute Show response attribute object
    • errors array[object] Required

      A list of errors that occurred in the failing request

      Hide errors attributes Show errors attributes object
      • code string Required

        A structured code representing the error type that occurred

      • message string Required

        A human readable message describing the error that occurred

      • fields array[string]

        If the error can be tied to a specific field or fields in the user request, this lists those fields

GET /account
curl \
 -X GET https://api.elastic-cloud.com/api/v1/account
Response examples (200)
{
  "id": "string",
  "trust": {
    "trust_all": true
  }
}
Response examples (404)
# Headers
x-cloud-error-codes: accounts.not_found

# Payload
{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "fields": [
        "string"
      ]
    }
  ]
}

Updates the current account

PUT /account

Updates the current account.

Body Required

the current account

  • trust object

    Settings related to the level of trust of the clusters in this account

    Additional properties are allowed.

    Hide trust attribute Show trust attribute object
    • trust_all boolean Required

      If true, all clusters in this account will by default trust all other clusters in the same account

Responses

  • Account updated successfully

    Hide response attributes Show response attributes object
    • id string Required

      The account's identifier

    • trust object

      Settings related to the level of trust of the clusters in this account

      Additional properties are allowed.

      Hide trust attribute Show trust attribute object
      • trust_all boolean Required

        If true, all clusters in this account will by default trust all other clusters in the same account

  • Account not found. (code: accounts.not_found)

    Hide headers attribute Show headers attribute
    Hide response attribute Show response attribute object
    • errors array[object] Required

      A list of errors that occurred in the failing request

      Hide errors attributes Show errors attributes object
      • code string Required

        A structured code representing the error type that occurred

      • message string Required

        A human readable message describing the error that occurred

      • fields array[string]

        If the error can be tied to a specific field or fields in the user request, this lists those fields

PUT /account
curl \
 -X PUT https://api.elastic-cloud.com/api/v1/account \
 -d '{"trust":{"trust_all":true}}'
Request examples
{
  "trust": {
    "trust_all": true
  }
}
Response examples (200)
{
  "id": "string",
  "trust": {
    "trust_all": true
  }
}
Response examples (404)
# Headers
x-cloud-error-codes: accounts.not_found

# Payload
{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "fields": [
        "string"
      ]
    }
  ]
}

Updates the current account

PATCH /account

Updates the current account.

Body Required

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.

string string

Responses

  • Account updated successfully

    Hide response attributes Show response attributes object
    • id string Required

      The account's identifier

    • trust object

      Settings related to the level of trust of the clusters in this account

      Additional properties are allowed.

      Hide trust attribute Show trust attribute object
      • trust_all boolean Required

        If true, all clusters in this account will by default trust all other clusters in the same account

  • Account not found. (code: accounts.not_found)

    Hide headers attribute Show headers attribute
    Hide response attribute Show response attribute object
    • errors array[object] Required

      A list of errors that occurred in the failing request

      Hide errors attributes Show errors attributes object
      • code string Required

        A structured code representing the error type that occurred

      • message string Required

        A human readable message describing the error that occurred

      • fields array[string]

        If the error can be tied to a specific field or fields in the user request, this lists those fields

PATCH /account
curl \
 -X PATCH https://api.elastic-cloud.com/api/v1/account \
 -d '"string"'
Request examples
string
Response examples (200)
{
  "id": "string",
  "trust": {
    "trust_all": true
  }
}
Response examples (404)
# Headers
x-cloud-error-codes: accounts.not_found

# Payload
{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "fields": [
        "string"
      ]
    }
  ]
}

Authentication

Manage your Elasticsearch Service API keys.

Get all API keys

GET /users/auth/keys

Retrieves the metadata for all of the API keys that the user generated.

Responses

  • The metadata for the API keys is retrieved.

    Hide response attribute Show response attribute object
    • keys array[object] Required

      The list of API keys.

      Hide keys attributes Show keys attributes object
      • id string Required

        The API key ID.

      • user_id string

        The user ID.

      • The organization ID linked to the API key

      • description string Required

        The API key description. TIP: Useful when you have multiple API keys.

      • key string

        The API key. TIP: Since the API key is returned only once, save it in a safe place.

      • creation_date string(date-time) Required

        The date/time for when the API key is created.

      • expiration_date string(date-time)

        The date/time when the API key expires.

      • The roles that will be assigned to users once they accept the invitation. Currently unavailable in self-hosted ECE.

        Additional properties are allowed.

        Hide role_assignments attributes Show role_assignments attributes object
        • platform array[object]

          Assignments for roles with platform scope.

          Hide platform attribute Show platform attribute object
          • role_id string Required

            The ID of the role that is assigned.

        • organization array[object]

          Assignments for roles with organization scope.

          Hide organization attributes Show organization attributes object
          • role_id string Required

            The ID of the role that is assigned.

          • organization_id string Required

            The ID of the organization the role is scoped to.

        • deployment array[object]

          Assignments for roles with deployment scope.

          Hide deployment attributes Show deployment attributes object
          • role_id string Required

            The ID of the role that is assigned.

          • organization_id string Required

            The ID of the organization the role is scoped to.

          • all boolean

            When true, the role applies to all deployments in the organization, otherwise the role is scoped to the deployments specified in deployment_ids.

          • deployment_ids array[string]

            The IDs of the deployments the role is scoped to. Must be absent if all is true, and present if all is false.

          • application_roles array[string]

            If provided, the user assigned this role assignment will be granted this application role when signing in to the deployment(s) specified in the role assignment.

        • project object

          Assignments for roles with project scope.

          Additional properties are allowed.

          Hide project attributes Show project attributes object
          • elasticsearch array[object]

            The Elasticsearch project-scoped role assignments to set

            Hide elasticsearch attributes Show elasticsearch attributes object
            • role_id string Required

              The ID of the role that is assigned.

            • organization_id string Required

              The ID of the organization the role is scoped to.

            • all boolean

              When true, the role applies to all projects in the organization, otherwise the role is scoped to the projects specified in project_ids.

            • project_ids array[string]

              The IDs of the projects the role is scoped to. Must be absent if all is true, and present if all is false.

            • application_roles array[string]

              If provided, the user assigned this role assignment will be granted this application role when signing in to the project(s) specified in the role assignment.

          • observability array[object]

            The Observability project-scoped role assignments to set

            Hide observability attributes Show observability attributes object
            • role_id string Required

              The ID of the role that is assigned.

            • organization_id string Required

              The ID of the organization the role is scoped to.

            • all boolean

              When true, the role applies to all projects in the organization, otherwise the role is scoped to the projects specified in project_ids.

            • project_ids array[string]

              The IDs of the projects the role is scoped to. Must be absent if all is true, and present if all is false.

            • application_roles array[string]

              If provided, the user assigned this role assignment will be granted this application role when signing in to the project(s) specified in the role assignment.

          • security array[object]

            The Security project-scoped role assignments to set

            Hide security attributes Show security attributes object
            • role_id string Required

              The ID of the role that is assigned.

            • organization_id string Required

              The ID of the organization the role is scoped to.

            • all boolean

              When true, the role applies to all projects in the organization, otherwise the role is scoped to the projects specified in project_ids.

            • project_ids array[string]

              The IDs of the projects the role is scoped to. Must be absent if all is true, and present if all is false.

            • application_roles array[string]

              If provided, the user assigned this role assignment will be granted this application role when signing in to the project(s) specified in the role assignment.

GET /users/auth/keys
curl \
 -X GET https://api.elastic-cloud.com/api/v1/users/auth/keys
Response examples (200)
{
  "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"
              ]
            }
          ]
        }
      }
    }
  ]
}

Create API key

POST /users/auth/keys

Creates a new API key.

Body Required

The request to create the API key

  • description string Required

    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.

    Hide role_assignments attributes Show role_assignments attributes object
    • platform array[object]

      Assignments for roles with platform scope.

      Hide platform attribute Show platform attribute object
      • role_id string Required

        The ID of the role that is assigned.

    • organization array[object]

      Assignments for roles with organization scope.

      Hide organization attributes Show organization attributes object
      • role_id string Required

        The ID of the role that is assigned.

      • organization_id string Required

        The ID of the organization the role is scoped to.

    • deployment array[object]

      Assignments for roles with deployment scope.

      Hide deployment attributes Show deployment attributes object
      • role_id string Required

        The ID of the role that is assigned.

      • organization_id string Required

        The ID of the organization the role is scoped to.

      • all boolean

        When true, the role applies to all deployments in the organization, otherwise the role is scoped to the deployments specified in deployment_ids.

      • deployment_ids array[string]

        The IDs of the deployments the role is scoped to. Must be absent if all is true, and present if all is false.

      • application_roles array[string]

        If provided, the user assigned this role assignment will be granted this application role when signing in to the deployment(s) specified in the role assignment.

    • project object

      Assignments for roles with project scope.

      Additional properties are allowed.

      Hide project attributes Show project attributes object
      • elasticsearch array[object]

        The Elasticsearch project-scoped role assignments to set

        Hide elasticsearch attributes Show elasticsearch attributes object
        • role_id string Required

          The ID of the role that is assigned.

        • organization_id string Required

          The ID of the organization the role is scoped to.

        • all boolean

          When true, the role applies to all projects in the organization, otherwise the role is scoped to the projects specified in project_ids.

        • project_ids array[string]

          The IDs of the projects the role is scoped to. Must be absent if all is true, and present if all is false.

        • application_roles array[string]

          If provided, the user assigned this role assignment will be granted this application role when signing in to the project(s) specified in the role assignment.

      • observability array[object]

        The Observability project-scoped role assignments to set

        Hide observability attributes Show observability attributes object
        • role_id string Required

          The ID of the role that is assigned.

        • organization_id string Required

          The ID of the organization the role is scoped to.

        • all boolean

          When true, the role applies to all projects in the organization, otherwise the role is scoped to the projects specified in project_ids.

        • project_ids array[string]

          The IDs of the projects the role is scoped to. Must be absent if all is true, and present if all is false.

        • application_roles array[string]

          If provided, the user assigned this role assignment will be granted this application role when signing in to the project(s) specified in the role assignment.

      • security array[object]

        The Security project-scoped role assignments to set

        Hide security attributes Show security attributes object
        • role_id string Required

          The ID of the role that is assigned.

        • organization_id string Required

          The ID of the organization the role is scoped to.

        • all boolean

          When true, the role applies to all projects in the organization, otherwise the role is scoped to the projects specified in project_ids.

        • project_ids array[string]

          The IDs of the projects the role is scoped to. Must be absent if all is true, and present if all is false.

        • application_roles array[string]

          If provided, the user assigned this role assignment will be granted this application role when signing in to the project(s) specified in the role assignment.

Responses

  • The API key is created and returned in the body of the response.

    Hide response attributes Show response attributes object
    • id string Required

      The API key ID.

    • user_id string

      The user ID.

    • The organization ID linked to the API key

    • description string Required

      The API key description. TIP: Useful when you have multiple API keys.

    • key string

      The API key. TIP: Since the API key is returned only once, save it in a safe place.

    • creation_date string(date-time) Required

      The date/time for when the API key is created.

    • expiration_date string(date-time)

      The date/time when the API key expires.

    • The roles that will be assigned to users once they accept the invitation. Currently unavailable in self-hosted ECE.

      Additional properties are allowed.

      Hide role_assignments attributes Show role_assignments attributes object
      • platform array[object]

        Assignments for roles with platform scope.

        Hide platform attribute Show platform attribute object
        • role_id string Required

          The ID of the role that is assigned.

      • organization array[object]

        Assignments for roles with organization scope.

        Hide organization attributes Show organization attributes object
        • role_id string Required

          The ID of the role that is assigned.

        • organization_id string Required

          The ID of the organization the role is scoped to.

      • deployment array[object]

        Assignments for roles with deployment scope.

        Hide deployment attributes Show deployment attributes object
        • role_id string Required

          The ID of the role that is assigned.

        • organization_id string Required

          The ID of the organization the role is scoped to.

        • all boolean

          When true, the role applies to all deployments in the organization, otherwise the role is scoped to the deployments specified in deployment_ids.

        • deployment_ids array[string]

          The IDs of the deployments the role is scoped to. Must be absent if all is true, and present if all is false.

        • application_roles array[string]

          If provided, the user assigned this role assignment will be granted this application role when signing in to the deployment(s) specified in the role assignment.

      • project object

        Assignments for roles with project scope.

        Additional properties are allowed.

        Hide project attributes Show project attributes object
        • elasticsearch array[object]

          The Elasticsearch project-scoped role assignments to set

          Hide elasticsearch attributes Show elasticsearch attributes object
          • role_id string Required

            The ID of the role that is assigned.

          • organization_id string Required

            The ID of the organization the role is scoped to.

          • all boolean

            When true, the role applies to all projects in the organization, otherwise the role is scoped to the projects specified in project_ids.

          • project_ids array[string]

            The IDs of the projects the role is scoped to. Must be absent if all is true, and present if all is false.

          • application_roles array[string]

            If provided, the user assigned this role assignment will be granted this application role when signing in to the project(s) specified in the role assignment.

        • observability array[object]

          The Observability project-scoped role assignments to set

          Hide observability attributes Show observability attributes object
          • role_id string Required

            The ID of the role that is assigned.

          • organization_id string Required

            The ID of the organization the role is scoped to.

          • all boolean

            When true, the role applies to all projects in the organization, otherwise the role is scoped to the projects specified in project_ids.

          • project_ids array[string]

            The IDs of the projects the role is scoped to. Must be absent if all is true, and present if all is false.

          • application_roles array[string]

            If provided, the user assigned this role assignment will be granted this application role when signing in to the project(s) specified in the role assignment.

        • security array[object]

          The Security project-scoped role assignments to set

          Hide security attributes Show security attributes object
          • role_id string Required

            The ID of the role that is assigned.

          • organization_id string Required

            The ID of the organization the role is scoped to.

          • all boolean

            When true, the role applies to all projects in the organization, otherwise the role is scoped to the projects specified in project_ids.

          • project_ids array[string]

            The IDs of the projects the role is scoped to. Must be absent if all is true, and present if all is false.

          • application_roles array[string]

            If provided, the user assigned this role assignment will be granted this application role when signing in to the project(s) specified in the role assignment.

  • The request is invalid. Specify a different request, then try again. (code: api_keys.invalid_input)

    Hide headers attribute Show headers attribute
    • The error codes associated with the response

      Value is api_keys.invalid_input.

    Hide response attribute Show response attribute object
    • errors array[object] Required

      A list of errors that occurred in the failing request

      Hide errors attributes Show errors attributes object
      • code string Required

        A structured code representing the error type that occurred

      • message string Required

        A human readable message describing the error that occurred

      • fields array[string]

        If the error can be tied to a specific field or fields in the user request, this lists those fields

POST /users/auth/keys
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"]}]}}}'
Request examples
{
  "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"
          ]
        }
      ]
    }
  }
}
Response examples (201)
{
  "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"
          ]
        }
      ]
    }
  }
}
Response examples (400)
# Headers
x-cloud-error-codes: api_keys.invalid_input

# Payload
{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "fields": [
        "string"
      ]
    }
  ]
}

Delete API keys

DELETE /users/auth/keys

Delete or invalidate API keys.

Body Required

The request to delete API keys

  • keys array[string] Required

    The list of API key IDs.

Responses

  • The API keys are deleted.

    Additional properties are allowed.

DELETE /users/auth/keys
curl \
 -X DELETE https://api.elastic-cloud.com/api/v1/users/auth/keys \
 -d '{"keys":["string"]}'
Request examples
{
  "keys": [
    "string"
  ]
}
Response examples (200)
{}

Get API key

GET /users/auth/keys/{api_key_id}

Retrieves the metadata for an API key.

Path parameters

Responses

  • The API key metadata is retrieved.

    Hide response attributes Show response attributes object
    • id string Required

      The API key ID.

    • user_id string

      The user ID.

    • The organization ID linked to the API key

    • description string Required

      The API key description. TIP: Useful when you have multiple API keys.

    • key string

      The API key. TIP: Since the API key is returned only once, save it in a safe place.

    • creation_date string(date-time) Required

      The date/time for when the API key is created.

    • expiration_date string(date-time)

      The date/time when the API key expires.

    • The roles that will be assigned to users once they accept the invitation. Currently unavailable in self-hosted ECE.

      Additional properties are allowed.

      Hide role_assignments attributes Show role_assignments attributes object
      • platform array[object]

        Assignments for roles with platform scope.

        Hide platform attribute Show platform attribute object
        • role_id string Required

          The ID of the role that is assigned.

      • organization array[object]

        Assignments for roles with organization scope.

        Hide organization attributes Show organization attributes object
        • role_id string Required

          The ID of the role that is assigned.

        • organization_id string Required

          The ID of the organization the role is scoped to.

      • deployment array[object]

        Assignments for roles with deployment scope.

        Hide deployment attributes Show deployment attributes object
        • role_id string Required

          The ID of the role that is assigned.

        • organization_id string Required

          The ID of the organization the role is scoped to.

        • all boolean

          When true, the role applies to all deployments in the organization, otherwise the role is scoped to the deployments specified in deployment_ids.

        • deployment_ids array[string]

          The IDs of the deployments the role is scoped to. Must be absent if all is true, and present if all is false.

        • application_roles array[string]

          If provided, the user assigned this role assignment will be granted this application role when signing in to the deployment(s) specified in the role assignment.

      • project object

        Assignments for roles with project scope.

        Additional properties are allowed.

        Hide project attributes Show project attributes object
        • elasticsearch array[object]

          The Elasticsearch project-scoped role assignments to set

          Hide elasticsearch attributes Show elasticsearch attributes object
          • role_id string Required

            The ID of the role that is assigned.

          • organization_id string Required

            The ID of the organization the role is scoped to.

          • all boolean

            When true, the role applies to all projects in the organization, otherwise the role is scoped to the projects specified in project_ids.

          • project_ids array[string]

            The IDs of the projects the role is scoped to. Must be absent if all is true, and present if all is false.

          • application_roles array[string]

            If provided, the user assigned this role assignment will be granted this application role when signing in to the project(s) specified in the role assignment.

        • observability array[object]

          The Observability project-scoped role assignments to set

          Hide observability attributes Show observability attributes object
          • role_id string Required

            The ID of the role that is assigned.

          • organization_id string Required

            The ID of the organization the role is scoped to.

          • all boolean

            When true, the role applies to all projects in the organization, otherwise the role is scoped to the projects specified in project_ids.

          • project_ids array[string]

            The IDs of the projects the role is scoped to. Must be absent if all is true, and present if all is false.

          • application_roles array[string]

            If provided, the user assigned this role assignment will be granted this application role when signing in to the project(s) specified in the role assignment.

        • security array[object]

          The Security project-scoped role assignments to set

          Hide security attributes Show security attributes object
          • role_id string Required

            The ID of the role that is assigned.

          • organization_id string Required

            The ID of the organization the role is scoped to.

          • all boolean

            When true, the role applies to all projects in the organization, otherwise the role is scoped to the projects specified in project_ids.

          • project_ids array[string]

            The IDs of the projects the role is scoped to. Must be absent if all is true, and present if all is false.

          • application_roles array[string]

            If provided, the user assigned this role assignment will be granted this application role when signing in to the project(s) specified in the role assignment.

  • The {api_key_id} can't be found. (code: api_keys.key_not_found)

    Hide headers attribute Show headers attribute
    • The error codes associated with the response

      Value is api_keys.key_not_found.

    Hide response attribute Show response attribute object
    • errors array[object] Required

      A list of errors that occurred in the failing request

      Hide errors attributes Show errors attributes object
      • code string Required

        A structured code representing the error type that occurred

      • message string Required

        A human readable message describing the error that occurred

      • fields array[string]

        If the error can be tied to a specific field or fields in the user request, this lists those fields

GET /users/auth/keys/{api_key_id}
curl \
 -X GET https://api.elastic-cloud.com/api/v1/users/auth/keys/{api_key_id}
Response examples (200)
{
  "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"
          ]
        }
      ]
    }
  }
}
Response examples (404)
# Headers
x-cloud-error-codes: api_keys.key_not_found

# Payload
{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "fields": [
        "string"
      ]
    }
  ]
}

Delete API key

DELETE /users/auth/keys/{api_key_id}

Delete or invalidate the API key.

Path parameters

Responses

  • The API key is deleted.

    Additional properties are allowed.

  • The {api_key_id} can't be found. (code: api_keys.key_not_found)

    Hide headers attribute Show headers attribute
    • The error codes associated with the response

      Value is api_keys.key_not_found.

    Hide response attribute Show response attribute object
    • errors array[object] Required

      A list of errors that occurred in the failing request

      Hide errors attributes Show errors attributes object
      • code string Required

        A structured code representing the error type that occurred

      • message string Required

        A human readable message describing the error that occurred

      • fields array[string]

        If the error can be tied to a specific field or fields in the user request, this lists those fields

DELETE /users/auth/keys/{api_key_id}
curl \
 -X DELETE https://api.elastic-cloud.com/api/v1/users/auth/keys/{api_key_id}
Response examples (200)
{}
Response examples (404)
# Headers
x-cloud-error-codes: api_keys.key_not_found

# Payload
{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "fields": [
        "string"
      ]
    }
  ]
}

Billing costs analysis

Get an overview of your costs by organization ID.

Get costs overview for the organization. Currently unavailable in self-hosted ECE. Deprecated

GET /billing/costs/{organization_id}

EXPERIMENTAL (it may change in future versions): Retrieves an overview of the costs by organization ID.

Path parameters

Query parameters

  • from string

    A datetime for the beginning of the desired range for which to fetch costs. Defaults to start of current month.

  • to string

    A datetime for the end of the desired range for which to fetch costs. Defaults to the current date.

Responses

  • Top-level cost overview for the organization

    Hide response attributes Show response attributes object
    • costs object Required

      Costs for the organization

      Additional properties are allowed.

      Hide costs attributes Show costs attributes object
      • total number(double) Required

        Total costs

      • dimensions array[object] Required

        A collection of billing details by dimension.

        Hide dimensions attributes Show dimensions attributes object
        • type string Required

          The type of the billing dimension

          Values are capacity, data_in, data_internode, data_out, storage_api, or storage_bytes.

        • cost number(double) Required

          The cost of the billing dimension

    • trials number(double) Required

      Trial costs for the organization

    • hourly_rate number(double) Required

      Hourly rate applied.

    • balance object

      Balance for the organization

      Additional properties are allowed.

      Hide balance attributes Show balance attributes object
      • available number(double) Required

        Available balance

      • remaining number(double) Required

        Remaining balance

      • line_items array[object] Required

        A collection of order line items for for an organization

        Hide line_items attributes Show line_items attributes object
        • id string Required

          Line Item ID

        • ecu_quantity number(double) Required

          Original Elastic Consumption Unit (ECU) quantity

        • ecu_balance number(double) Required

          Elastic Consumption Unit (ECU) Balance

        • start string(date-time) Required

          Start of the line item's validity

        • end string(date-time) Required

          Expiration of the line item

  • The specified date range is invalid. (code: costs.invalid_date_range)

    Hide headers attribute Show headers attribute
    • The error codes associated with the response

      Value is costs.invalid_date_range.

    Hide response attribute Show response attribute object
    • errors array[object] Required

      A list of errors that occurred in the failing request

      Hide errors attributes Show errors attributes object
      • code string Required

        A structured code representing the error type that occurred

      • message string Required

        A human readable message describing the error that occurred

      • fields array[string]

        If the error can be tied to a specific field or fields in the user request, this lists those fields

  • The current user does not have access to the requested organization. (code: organization.invalid_access)

    Hide headers attribute Show headers attribute
    • The error codes associated with the response

      Value is organization.invalid_access.

    Hide response attribute Show response attribute object
    • errors array[object] Required

      A list of errors that occurred in the failing request

      Hide errors attributes Show errors attributes object
      • code string Required

        A structured code representing the error type that occurred

      • message string Required

        A human readable message describing the error that occurred

      • fields array[string]

        If the error can be tied to a specific field or fields in the user request, this lists those fields

  • Organization not found. (code: organization.not_found)

    Hide headers attribute Show headers attribute
    • The error codes associated with the response

      Value is organization.not_found.

    Hide response attribute Show response attribute object
    • errors array[object] Required

      A list of errors that occurred in the failing request

      Hide errors attributes Show errors attributes object
      • code string Required

        A structured code representing the error type that occurred

      • message string Required

        A human readable message describing the error that occurred

      • fields array[string]

        If the error can be tied to a specific field or fields in the user request, this lists those fields

  • An error occurred when fetching an overview of the costs for the organization. (code: billing_service.failed_request)

    Hide headers attribute Show headers attribute
    • The error codes associated with the response

      Value is billing_service.failed_request.

    Hide response attribute Show response attribute object
    • errors array[object] Required

      A list of errors that occurred in the failing request

      Hide errors attributes Show errors attributes object
      • code string Required

        A structured code representing the error type that occurred

      • message string Required

        A human readable message describing the error that occurred

      • fields array[string]

        If the error can be tied to a specific field or fields in the user request, this lists those fields

GET /billing/costs/{organization_id}
curl \
 -X GET https://api.elastic-cloud.com/api/v1/billing/costs/{organization_id}
Response examples (200)
{
  "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"
      }
    ]
  }
}
Response examples (400)
# Headers
x-cloud-error-codes: costs.invalid_date_range

# Payload
{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "fields": [
        "string"
      ]
    }
  ]
}
Response examples (403)
# Headers
x-cloud-error-codes: organization.invalid_access

# Payload
{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "fields": [
        "string"
      ]
    }
  ]
}
Response examples (404)
# Headers
x-cloud-error-codes: organization.not_found

# Payload
{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "fields": [
        "string"
      ]
    }
  ]
}
Response examples (500)
# Headers
x-cloud-error-codes: billing_service.failed_request

# Payload
{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "fields": [
        "string"
      ]
    }
  ]
}

Get charts for the organization. Currently unavailable in self-hosted ECE. Deprecated

GET /billing/costs/{organization_id}/charts

EXPERIMENTAL (it may change in future versions): Retrieves the usage charts for the organization.

Path parameters

Query parameters

  • from string

    A datetime for the beginning of the desired range for which to fetch costs. Defaults to start of current month.

  • to string

    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.

Responses

  • The usage charts of an organization.

    Hide response attribute Show response attribute object
    • data array[object] Required

      The list of chart item

      Hide data attributes Show data attributes object
      • timestamp integer(int64) Required

        Axis X position

      • values array[object] Required

        the collection of values to plot the chart item

        Hide values attributes Show values attributes object
        • id string Required

          The id of chart item value

        • name string Required

          The name of the chart item value

        • value number(double) Required

          The actual value of the chart item value

  • The specified date range is invalid. (code: costs.invalid_date_range)

    Hide headers attribute Show headers attribute
    • The error codes associated with the response

      Value is costs.invalid_date_range.

    Hide response attribute Show response attribute object
    • errors array[object] Required

      A list of errors that occurred in the failing request

      Hide errors attributes Show errors attributes object
      • code string Required

        A structured code representing the error type that occurred

      • message string Required

        A human readable message describing the error that occurred

      • fields array[string]

        If the error can be tied to a specific field or fields in the user request, this lists those fields

  • The current user does not have access to the requested organization. (code: organization.invalid_access)

    Hide headers attribute Show headers attribute
    • The error codes associated with the response

      Value is organization.invalid_access.

    Hide response attribute Show response attribute object
    • errors array[object] Required

      A list of errors that occurred in the failing request

      Hide errors attributes Show errors attributes object
      • code string Required

        A structured code representing the error type that occurred

      • message string Required

        A human readable message describing the error that occurred

      • fields array[string]

        If the error can be tied to a specific field or fields in the user request, this lists those fields

  • Organization not found. (code: organization.not_found)

    Hide headers attribute Show headers attribute
    • The error codes associated with the response

      Value is organization.not_found.

    Hide response attribute Show response attribute object
    • errors array[object] Required

      A list of errors that occurred in the failing request

      Hide errors attributes Show errors attributes object
      • code string Required

        A structured code representing the error type that occurred

      • message string Required

        A human readable message describing the error that occurred

      • fields array[string]

        If the error can be tied to a specific field or fields in the user request, this lists those fields

  • Too many requests. (code: billing_service.rate_limited)

    Hide headers attribute Show headers attribute
    • The error codes associated with the response

      Value is billing_service.rate_limited.

    Hide response attribute Show response attribute object
    • errors array[object] Required

      A list of errors that occurred in the failing request

      Hide errors attributes Show errors attributes object
      • code string Required

        A structured code representing the error type that occurred

      • message string Required

        A human readable message describing the error that occurred

      • fields array[string]

        If the error can be tied to a specific field or fields in the user request, this lists those fields

  • Error fetching the itemized costs for the organization. (code: billing_service.failed_request)

    Hide headers attribute Show headers attribute
    • The error codes associated with the response

      Value is billing_service.failed_request.

    Hide response attribute Show response attribute object
    • errors array[object] Required

      A list of errors that occurred in the failing request

      Hide errors attributes Show errors attributes object
      • code string Required

        A structured code representing the error type that occurred

      • message string Required

        A human readable message describing the error that occurred

      • fields array[string]

        If the error can be tied to a specific field or fields in the user request, this lists those fields

GET /billing/costs/{organization_id}/charts
curl \
 -X GET https://api.elastic-cloud.com/api/v1/billing/costs/{organization_id}/charts
Response examples (200)
{
  "data": [
    {
      "timestamp": 42,
      "values": [
        {
          "id": "string",
          "name": "string",
          "value": 42.0
        }
      ]
    }
  ]
}
Response examples (400)
# Headers
x-cloud-error-codes: costs.invalid_date_range

# Payload
{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "fields": [
        "string"
      ]
    }
  ]
}
Response examples (403)
# Headers
x-cloud-error-codes: organization.invalid_access

# Payload
{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "fields": [
        "string"
      ]
    }
  ]
}
Response examples (404)
# Headers
x-cloud-error-codes: organization.not_found

# Payload
{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "fields": [
        "string"
      ]
    }
  ]
}
Response examples (429)
# Headers
x-cloud-error-codes: billing_service.rate_limited

# Payload
{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "fields": [
        "string"
      ]
    }
  ]
}
Response examples (500)
# Headers
x-cloud-error-codes: billing_service.failed_request

# Payload
{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "fields": [
        "string"
      ]
    }
  ]
}

Get deployments costs for the organization. Currently unavailable in self-hosted ECE. Deprecated

GET /billing/costs/{organization_id}/deployments

EXPERIMENTAL (it may change in future versions): Retrieves the costs associated with all deployments for the organization.

Headers

  • Accept string

    Accept header containing the content preference.

Path parameters

Query parameters

  • from string

    A datetime for the beginning of the desired range for which to fetch activity. Defaults to start of current month.

  • to string

    A datetime for the end of the desired range for which to fetch activity. Defaults to the current date.

Responses

  • The costs associated to a set of products

    Hide response attributes Show response attributes object
    • total_cost number(double) Required

      Total cost for all deployments

    • deployments array[object] Required

      Costs of the list of deployments

      Hide deployments attributes Show deployments attributes object
      • deployment_id string Required

        Elasticsearch deployment id

      • deployment_name string Required

        Elasticsearch deployment name

      • costs object Required

        Costs for the organization

        Additional properties are allowed.

        Hide costs attributes Show costs attributes object
        • total number(double) Required

          Total costs

        • dimensions array[object] Required

          A collection of billing details by dimension.

          Hide dimensions attributes Show dimensions attributes object
          • type string Required

            The type of the billing dimension

            Values are capacity, data_in, data_internode, data_out, storage_api, or storage_bytes.

          • cost number(double) Required

            The cost of the billing dimension

      • hourly_rate number(double) Required

        Price per hour

      • period object

        Period

        Additional properties are allowed.

        Hide period attributes Show period attributes object
        • start string(date-time) Required

          Start

        • end string(date-time) Required

          End

  • Invalid date range specified. (code: costs.invalid_date_range)

    Hide headers attribute Show headers attribute
    • The error codes associated with the response

      Value is costs.invalid_date_range.

    Hide response attribute Show response attribute object
    • errors array[object] Required

      A list of errors that occurred in the failing request

      Hide errors attributes Show errors attributes object
      • code string Required

        A structured code representing the error type that occurred

      • message string Required

        A human readable message describing the error that occurred

      • fields array[string]

        If the error can be tied to a specific field or fields in the user request, this lists those fields

  • The current user does not have access to the requested organization. (code: organization.invalid_access)

    Hide headers attribute Show headers attribute
    • The error codes associated with the response

      Value is organization.invalid_access.

    Hide response attribute Show response attribute object
    • errors array[object] Required

      A list of errors that occurred in the failing request

      Hide errors attributes Show errors attributes object
      • code string Required

        A structured code representing the error type that occurred

      • message string Required

        A human readable message describing the error that occurred

      • fields array[string]

        If the error can be tied to a specific field or fields in the user request, this lists those fields

  • Organization not found. (code: organization.not_found)

    Hide headers attribute Show headers attribute
    • The error codes associated with the response

      Value is organization.not_found.

    Hide response attribute Show response attribute object
    • errors array[object] Required

      A list of errors that occurred in the failing request

      Hide errors attributes Show errors attributes object
      • code string Required

        A structured code representing the error type that occurred

      • message string Required

        A human readable message describing the error that occurred

      • fields array[string]

        If the error can be tied to a specific field or fields in the user request, this lists those fields

  • An error occurred when fetching the costs associated with all deployments for the organization. (code: billing_service.failed_request)

    Hide headers attribute Show headers attribute
    • The error codes associated with the response

      Value is billing_service.failed_request.

    Hide response attribute Show response attribute object
    • errors array[object] Required

      A list of errors that occurred in the failing request

      Hide errors attributes Show errors attributes object
      • code string Required

        A structured code representing the error type that occurred

      • message string Required

        A human readable message describing the error that occurred

      • fields array[string]

        If the error can be tied to a specific field or fields in the user request, this lists those fields

GET /billing/costs/{organization_id}/deployments
curl \
 -X GET https://api.elastic-cloud.com/api/v1/billing/costs/{organization_id}/deployments \
 -H "Accept: string"
Response examples (200)
{
  "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"
      }
    }
  ]
}
Response examples (400)
# Headers
x-cloud-error-codes: costs.invalid_date_range

# Payload
{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "fields": [
        "string"
      ]
    }
  ]
}
Response examples (403)
# Headers
x-cloud-error-codes: organization.invalid_access

# Payload
{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "fields": [
        "string"
      ]
    }
  ]
}
Response examples (404)
# Headers
x-cloud-error-codes: organization.not_found

# Payload
{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "fields": [
        "string"
      ]
    }
  ]
}
Response examples (500)
# Headers
x-cloud-error-codes: billing_service.failed_request

# Payload
{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "fields": [
        "string"
      ]
    }
  ]
}

Get charts by deployment. Currently unavailable in self-hosted ECE. Deprecated

GET /billing/costs/{organization_id}/deployments/{deployment_id}/charts

EXPERIMENTAL (it may change in future versions): Retrieves the usage charts for the given deployment.

Path parameters

Query parameters

  • from string

    A datetime for the beginning of the desired range for which to fetch costs. Defaults to start of current month.

  • to string

    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.

Responses

  • The usage charts of a deployment.

    Hide response attribute Show response attribute object
    • data array[object] Required

      The list of chart item

      Hide data attributes Show data attributes object
      • timestamp integer(int64) Required

        Axis X position

      • values array[object] Required

        the collection of values to plot the chart item

        Hide values attributes Show values attributes object
        • id string Required

          The id of chart item value

        • name string Required

          The name of the chart item value

        • value number(double) Required

          The actual value of the chart item value

  • The specified date range is invalid. (code: costs.invalid_date_range)

    Hide headers attribute Show headers attribute
    • The error codes associated with the response

      Value is costs.invalid_date_range.

    Hide response attribute Show response attribute object
    • errors array[object] Required

      A list of errors that occurred in the failing request

      Hide errors attributes Show errors attributes object
      • code string Required

        A structured code representing the error type that occurred

      • message string Required

        A human readable message describing the error that occurred

      • fields array[string]

        If the error can be tied to a specific field or fields in the user request, this lists those fields

  • The current user does not have access to the requested organization. (code: organization.invalid_access)

    Hide headers attribute Show headers attribute
    • The error codes associated with the response

      Value is organization.invalid_access.

    Hide response attribute Show response attribute object
    • errors array[object] Required

      A list of errors that occurred in the failing request

      Hide errors attributes Show errors attributes object
      • code string Required

        A structured code representing the error type that occurred

      • message string Required

        A human readable message describing the error that occurred

      • fields array[string]

        If the error can be tied to a specific field or fields in the user request, this lists those fields

  • Organization not found. (code: organization.not_found)

    Hide headers attribute Show headers attribute
    • The error codes associated with the response

      Value is organization.not_found.

    Hide response attribute Show response attribute object
    • errors array[object] Required

      A list of errors that occurred in the failing request

      Hide errors attributes Show errors attributes object
      • code string Required

        A structured code representing the error type that occurred

      • message string Required

        A human readable message describing the error that occurred

      • fields array[string]

        If the error can be tied to a specific field or fields in the user request, this lists those fields

  • Too many requests. (code: billing_service.rate_limited)

    Hide headers attribute Show headers attribute
    • The error codes associated with the response

      Value is billing_service.rate_limited.

    Hide response attribute Show response attribute object
    • errors array[object] Required

      A list of errors that occurred in the failing request

      Hide errors attributes Show errors attributes object
      • code string Required

        A structured code representing the error type that occurred

      • message string Required

        A human readable message describing the error that occurred

      • fields array[string]

        If the error can be tied to a specific field or fields in the user request, this lists those fields

  • Error fetching the itemized costs for the organization. (code: billing_service.failed_request)

    Hide headers attribute Show headers attribute
    • The error codes associated with the response

      Value is billing_service.failed_request.

    Hide response attribute Show response attribute object
    • errors array[object] Required

      A list of errors that occurred in the failing request

      Hide errors attributes Show errors attributes object
      • code string Required

        A structured code representing the error type that occurred

      • message string Required

        A human readable message describing the error that occurred

      • fields array[string]

        If the error can be tied to a specific field or fields in the user request, this lists those fields

GET /billing/costs/{organization_id}/deployments/{deployment_id}/charts
curl \
 -X GET https://api.elastic-cloud.com/api/v1/billing/costs/{organization_id}/deployments/{deployment_id}/charts
Response examples (200)
{
  "data": [
    {
      "timestamp": 42,
      "values": [
        {
          "id": "string",
          "name": "string",
          "value": 42.0
        }
      ]
    }
  ]
}
Response examples (400)
# Headers
x-cloud-error-codes: costs.invalid_date_range

# Payload
{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "fields": [
        "string"
      ]
    }
  ]
}
Response examples (403)
# Headers
x-cloud-error-codes: organization.invalid_access

# Payload
{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "fields": [
        "string"
      ]
    }
  ]
}
Response examples (404)
# Headers
x-cloud-error-codes: organization.not_found

# Payload
{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "fields": [
        "string"
      ]
    }
  ]
}
Response examples (429)
# Headers
x-cloud-error-codes: billing_service.rate_limited

# Payload
{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "fields": [
        "string"
      ]
    }
  ]
}
Response examples (500)
# Headers
x-cloud-error-codes: billing_service.failed_request

# Payload
{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "fields": [
        "string"
      ]
    }
  ]
}

Get itemized costs by deployments. Currently unavailable in self-hosted ECE. Deprecated

GET /billing/costs/{organization_id}/deployments/{deployment_id}/items

EXPERIMENTAL (it may change in future versions): Retrieves the itemized costs for the given deployment.

Headers

  • Accept string

    Determines the response body format. Can be either application/json or text/csv.

Path parameters

Query parameters

  • from string

    A datetime for the beginning of the desired range for which to fetch costs. Defaults to start of current month.

  • to string

    A datetime for the end of the desired range for which to fetch costs. Defaults to the current date.

Responses

  • The costs associated to a set items billed for a single deployment.

    Hide response attributes Show response attributes object
    • costs object Required

      Costs for the organization

      Additional properties are allowed.

      Hide costs attributes Show costs attributes object
      • total number(double) Required

        Total costs

      • dimensions array[object] Required

        A collection of billing details by dimension.

        Hide dimensions attributes Show dimensions attributes object
        • type string Required

          The type of the billing dimension

          Values are capacity, data_in, data_internode, data_out, storage_api, or storage_bytes.

        • cost number(double) Required

          The cost of the billing dimension

    • data_transfer_and_storage array[object] Required

      List of the detailed costs associated to the Data Transfer and Storage (DTS) dimensions

      Hide data_transfer_and_storage attributes Show data_transfer_and_storage attributes object
      • cost number(double) Required

        Costs associated to the Data Transfer and Storage (DTS) dimensions for an organization

      • name string Required

        DTS dimension name

      • quantity object Required

        DTS usage

        Additional properties are allowed.

        Hide quantity attributes Show quantity attributes object
      • rate object Required

        Cost per unit

        Additional properties are allowed.

        Hide rate attributes Show rate attributes object
      • sku string Required

        DTS dimension Stock Keeping Unit (SKU)

      • type string Required

        Type of the DTS dimension usage

    • resources array[object] Required

      Costs of the list of resources

      Hide resources attributes Show resources attributes object
      • hours integer(int64) Required

        Resource usage in hours

      • instance_count integer(int32) Required

        Number of instances

      • period object Required

        Period

        Additional properties are allowed.

        Hide period attributes Show period attributes object
        • start string(date-time) Required

          Start

        • end string(date-time) Required

          End

      • kind string Required

        Kind of resource

        Values are elasticsearch, kibana, apm, integrations_server, appsearch, or enterprise_search.

      • price number(double) Required

        Resource price

      • price_per_hour number(double) Required

        Price per hour

      • name string Required

        Resource name

      • sku string Required

        Stock Keeping Unit (SKU)

  • The specified date range is invalid. (code: costs.invalid_date_range)

    Hide headers attribute Show headers attribute
    • The error codes associated with the response

      Value is costs.invalid_date_range.

    Hide response attribute Show response attribute object
    • errors array[object] Required

      A list of errors that occurred in the failing request

      Hide errors attributes Show errors attributes object
      • code string Required

        A structured code representing the error type that occurred

      • message string Required

        A human readable message describing the error that occurred

      • fields array[string]

        If the error can be tied to a specific field or fields in the user request, this lists those fields

  • The current user does not have access to the requested organization. (code: organization.invalid_access)

    Hide headers attribute Show headers attribute
    • The error codes associated with the response

      Value is organization.invalid_access.

    Hide response attribute Show response attribute object
    • errors array[object] Required

      A list of errors that occurred in the failing request

      Hide errors attributes Show errors attributes object
      • code string Required

        A structured code representing the error type that occurred

      • message string Required

        A human readable message describing the error that occurred

      • fields array[string]

        If the error can be tied to a specific field or fields in the user request, this lists those fields

    • The organization was not found. (code: organization.not_found)
    • The Elasticsearch cluster was not found. (code: billing_service.es_cluster_id_not_found)
    Hide headers attribute Show headers attribute
    • The error codes associated with the response

      Values are organization.not_found or billing_service.es_cluster_id_not_found.

    Hide response attribute Show response attribute object
    • errors array[object] Required

      A list of errors that occurred in the failing request

      Hide errors attributes Show errors attributes object
      • code string Required

        A structured code representing the error type that occurred

      • message string Required

        A human readable message describing the error that occurred

      • fields array[string]

        If the error can be tied to a specific field or fields in the user request, this lists those fields

  • An error occurred when fetching the itemized costs for the given deployment of the organization. (code: billing_service.failed_request)

    Hide headers attribute Show headers attribute
    • The error codes associated with the response

      Value is billing_service.failed_request.

    Hide response attribute Show response attribute object
    • errors array[object] Required

      A list of errors that occurred in the failing request

      Hide errors attributes Show errors attributes object
      • code string Required

        A structured code representing the error type that occurred

      • message string Required

        A human readable message describing the error that occurred

      • fields array[string]

        If the error can be tied to a specific field or fields in the user request, this lists those fields

GET /billing/costs/{organization_id}/deployments/{deployment_id}/items
curl \
 -X GET https://api.elastic-cloud.com/api/v1/billing/costs/{organization_id}/deployments/{deployment_id}/items \
 -H "Accept: string"
Response examples (200)
{
  "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"
    }
  ]
}
Response examples (400)
# Headers
x-cloud-error-codes: costs.invalid_date_range

# Payload
{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "fields": [
        "string"
      ]
    }
  ]
}
Response examples (403)
# Headers
x-cloud-error-codes: organization.invalid_access

# Payload
{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "fields": [
        "string"
      ]
    }
  ]
}
Response examples (404)
# Headers
x-cloud-error-codes: organization.not_found

# Payload
{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "fields": [
        "string"
      ]
    }
  ]
}
Response examples (500)
# Headers
x-cloud-error-codes: billing_service.failed_request

# Payload
{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "fields": [
        "string"
      ]
    }
  ]
}

Get itemized costs for the organization. Currently unavailable in self-hosted ECE. Deprecated

GET /billing/costs/{organization_id}/items

EXPERIMENTAL (it may change in future versions): Retrieves the itemized costs for the organization.

Path parameters

Query parameters

  • from string

    A datetime for the beginning of the desired range for which to fetch costs. Defaults to start of current month.

  • to string

    A datetime for the end of the desired range for which to fetch costs. Defaults to the current date.

Responses

  • The costs associated to a set of items

    Hide response attributes Show response attributes object
    • costs object Required

      Costs for the organization

      Additional properties are allowed.

      Hide costs attributes Show costs attributes object
      • total number(double) Required

        Total costs

      • dimensions array[object] Required

        A collection of billing details by dimension.

        Hide dimensions attributes Show dimensions attributes object
        • type string Required

          The type of the billing dimension

          Values are capacity, data_in, data_internode, data_out, storage_api, or storage_bytes.

        • cost number(double) Required

          The cost of the billing dimension

    • data_transfer_and_storage array[object] Required

      List of the detailed costs associated to the Data Transfer and Storage (DTS) dimensions

      Hide data_transfer_and_storage attributes Show data_transfer_and_storage attributes object
      • cost number(double) Required

        Costs associated to the Data Transfer and Storage (DTS) dimensions for an organization

      • name string Required

        DTS dimension name

      • quantity object Required

        DTS usage

        Additional properties are allowed.

        Hide quantity attributes Show quantity attributes object
      • rate object Required

        Cost per unit

        Additional properties are allowed.

        Hide rate attributes Show rate attributes object
      • sku string Required

        DTS dimension Stock Keeping Unit (SKU)

      • type string Required

        Type of the DTS dimension usage

    • resources array[object] Required

      Costs of the list of resources

      Hide resources attributes Show resources attributes object
      • hours integer(int64) Required

        Resource usage in hours

      • instance_count integer(int32) Required

        Number of instances

      • period object Required

        Period

        Additional properties are allowed.

        Hide period attributes Show period attributes object
        • start string(date-time) Required

          Start

        • end string(date-time) Required

          End

      • kind string Required

        Kind of resource

        Values are elasticsearch, kibana, apm, integrations_server, appsearch, or enterprise_search.

      • price number(double) Required

        Resource price

      • price_per_hour number(double) Required

        Price per hour

      • name string Required

        Resource name

      • sku string Required

        Stock Keeping Unit (SKU)

  • The specified date range is invalid. (code: costs.invalid_date_range)

    Hide headers attribute Show headers attribute
    • The error codes associated with the response

      Value is costs.invalid_date_range.

    Hide response attribute Show response attribute object
    • errors array[object] Required

      A list of errors that occurred in the failing request

      Hide errors attributes Show errors attributes object
      • code string Required

        A structured code representing the error type that occurred

      • message string Required

        A human readable message describing the error that occurred

      • fields array[string]

        If the error can be tied to a specific field or fields in the user request, this lists those fields

  • The current user does not have access to the requested organization. (code: organization.invalid_access)

    Hide headers attribute Show headers attribute
    • The error codes associated with the response

      Value is organization.invalid_access.

    Hide response attribute Show response attribute object
    • errors array[object] Required

      A list of errors that occurred in the failing request

      Hide errors attributes Show errors attributes object
      • code string Required

        A structured code representing the error type that occurred

      • message string Required

        A human readable message describing the error that occurred

      • fields array[string]

        If the error can be tied to a specific field or fields in the user request, this lists those fields

  • Organization not found. (code: organization.not_found)

    Hide headers attribute Show headers attribute
    • The error codes associated with the response

      Value is organization.not_found.

    Hide response attribute Show response attribute object
    • errors array[object] Required

      A list of errors that occurred in the failing request

      Hide errors attributes Show errors attributes object
      • code string Required

        A structured code representing the error type that occurred

      • message string Required

        A human readable message describing the error that occurred

      • fields array[string]

        If the error can be tied to a specific field or fields in the user request, this lists those fields

  • Error fetching the itemized costs for the organization. (code: billing_service.failed_request)

    Hide headers attribute Show headers attribute
    • The error codes associated with the response

      Value is billing_service.failed_request.

    Hide response attribute Show response attribute object
    • errors array[object] Required

      A list of errors that occurred in the failing request

      Hide errors attributes Show errors attributes object
      • code string Required

        A structured code representing the error type that occurred

      • message string Required

        A human readable message describing the error that occurred

      • fields array[string]

        If the error can be tied to a specific field or fields in the user request, this lists those fields

GET /billing/costs/{organization_id}/items
curl \
 -X GET https://api.elastic-cloud.com/api/v1/billing/costs/{organization_id}/items
Response examples (200)
{
  "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"
    }
  ]
}
Response examples (400)
# Headers
x-cloud-error-codes: costs.invalid_date_range

# Payload
{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "fields": [
        "string"
      ]
    }
  ]
}
Response examples (403)
# Headers
x-cloud-error-codes: organization.invalid_access

# Payload
{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "fields": [
        "string"
      ]
    }
  ]
}
Response examples (404)
# Headers
x-cloud-error-codes: organization.not_found

# Payload
{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "fields": [
        "string"
      ]
    }
  ]
}
Response examples (500)
# Headers
x-cloud-error-codes: billing_service.failed_request

# Payload
{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "fields": [
        "string"
      ]
    }
  ]
}

Deployments

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.