Digital Ocean Billing API

openapi: 3.2.0
info:
  title: DigitalOcean Billing API
  version: '2.0'
  description: 'The billing endpoints allow you to retrieve your account balance, invoices,

    billing history, insights, and prepayment information.


    **Balance:** By sending requests to the `/v2/customers/my/balance` endpoint, you can

    retrieve the balance information for the requested customer account.


    **Prepayment:** By sending requests to the `/v2/customers/my/prepayment_config`

    and `/v2/customers/my/prepayment_status` endpoints, you can retrieve prepayment

    gate configuration and status for the requested customer account.


    **Invoices:** Invoices

    are generated on the first of each month for every DigitalOcean

    customer. An invoice preview is generated daily, which can be accessed

    with the `preview` keyword in place of `$INVOICE_UUID`. To interact with

    invoices, you will generally send requests to the invoices endpoint at

    `/v2/customers/my/invoices`.


    **Billing History:** Billing history is a record of billing events for your account.

    For example, entries may include events like payments made, invoices

    issued, or credits granted. To interact with invoices, you

    will generally send requests to the invoices endpoint at

    `/v2/customers/my/billing_history`.


    **Billing Insights:** Day-over-day changes in billing resource usage based on nightly invoice items,

    including total amount, region, SKU, and description for a specified date range.

    It is important to note that the daily resource usage may not reflect month-end billing totals when totaled for

    a given month as nightly invoice items do not necessarily encompass all invoicing factors for the entire month.

    `v2/billing/{account_urn}/insights/{start_date}/{end_date}` where account_urn is the URN of the customer

    account, can be a team (do:team:uuid) or an organization (do:teamgroup:uuid). The date range specified by

    start_date and end_date must be in YYYY-MM-DD format.'
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  contact:
    name: DigitalOcean API Team
    email: api-engineering@digitalocean.com
  termsOfService: https://www.digitalocean.com/legal/terms-of-service-agreement/
servers:
- url: https://api.digitalocean.com
  description: production
security:
- bearer_auth: []
tags:
- name: Billing
  description: 'The billing endpoints allow you to retrieve your account balance, invoices,

    billing history, insights, and prepayment information.


    **Balance:** By sending requests to the `/v2/customers/my/balance` endpoint, you can

    retrieve the balance information for the requested customer account.


    **Prepayment:** By sending requests to the `/v2/customers/my/prepayment_config`

    and `/v2/customers/my/prepayment_status` endpoints, you can retrieve prepayment

    gate configuration and status for the requested customer account.


    **Invoices:** Invoices

    are generated on the first of each month for every DigitalOcean

    customer. An invoice preview is generated daily, which can be accessed

    with the `preview` keyword in place of `$INVOICE_UUID`. To interact with

    invoices, you will generally send requests to the invoices endpoint at

    `/v2/customers/my/invoices`.


    **Billing History:** Billing history is a record of billing events for your account.

    For example, entries may include events like payments made, invoices

    issued, or credits granted. To interact with invoices, you

    will generally send requests to the invoices endpoint at

    `/v2/customers/my/billing_history`.


    **Billing Insights:** Day-over-day changes in billing resource usage based on nightly invoice items,

    including total amount, region, SKU, and description for a specified date range.

    It is important to note that the daily resource usage may not reflect month-end billing totals when totaled for

    a given month as nightly invoice items do not necessarily encompass all invoicing factors for the entire month.

    `v2/billing/{account_urn}/insights/{start_date}/{end_date}` where account_urn is the URN of the customer

    account, can be a team (do:team:uuid) or an organization (do:teamgroup:uuid). The date range specified by

    start_date and end_date must be in YYYY-MM-DD format.'
paths:
  /v2/billing/{account_urn}/insights/{start_date}/{end_date}:
    get:
      $ref: resources/billing/billingInsights_list.yml
      tags:
      - Billing
      summary: Get billing by account urn insights by start date by end date
      x-summary-source: derived
      operationId: getV2BillingByAccountUrnInsightsByStartDateByEndDate
      x-operation-id-source: derived
components:
  securitySchemes:
    bearer_auth:
      type: http
      scheme: bearer
      description: '## OAuth Authentication


        In order to interact with the DigitalOcean API, you or your application must

        authenticate.


        The DigitalOcean API handles this through OAuth, an open standard for

        authorization. OAuth allows you to delegate access to your account.

        Scopes can be used to grant full access, read-only access, or access to

        a specific set of endpoints.


        You can generate an OAuth token by visiting the [Apps & API](https://cloud.digitalocean.com/account/api/tokens)

        section of the DigitalOcean control panel for your account.


        An OAuth token functions as a complete authentication request. In effect, it

        acts as a substitute for a username and password pair.


        Because of this, it is absolutely **essential** that you keep your OAuth

        tokens secure. In fact, upon generation, the web interface will only display

        each token a single time in order to prevent the token from being compromised.


        DigitalOcean access tokens begin with an identifiable prefix in order to

        distinguish them from other similar tokens.


        - `dop_v1_` for personal access tokens generated in the control panel

        - `doo_v1_` for tokens generated by applications using [the OAuth flow](https://docs.digitalocean.com/reference/api/oauth-api/)

        - `dor_v1_` for OAuth refresh tokens


        ### Scopes


        Scopes act like permissions assigned to an API token. These permissions

        determine what actions the token can perform. You can create API

        tokens that grant read-only access, full access, or limited access to

        specific endpoints by using custom scopes.


        Generally, scopes are designed to match HTTP verbs and common CRUD

        operations (Create, Read, Update, Delete).


        | HTTP Verb | CRUD Operation | Scope |

        |---|---|---|

        | GET | Read | `<resource>:read` |

        | POST | Create | `<resource>:create` |

        | PUT/PATCH | Update | `<resource>:update` |

        | DELETE | Delete | `<resource>:delete` |


        For example, creating a new Droplet by making a `POST` request to the

        `/v2/droplets` endpoint requires the `droplet:create` scope while

        listing Droplets by making a `GET` request to the `/v2/droplets`

        endpoint requires the `droplet:read` scope.


        Each endpoint below specifies which scope is required to access it when

        using custom scopes.


        ### How to Authenticate with OAuth


        In order to make an authenticated request, include a bearer-type

        `Authorization` header containing your OAuth token. All requests must be

        made over HTTPS.


        ### Authenticate with a Bearer Authorization Header


        ```

        curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

        ```

        '
    inference_bearer_auth:
      type: http
      scheme: bearer
      description: '## OAuth Authentication


        In order to interact with the DigitalOcean API, you or your application must

        authenticate.


        The DigitalOcean API handles this through OAuth, an open standard for

        authorization. OAuth allows you to delegate access to your account.

        Scopes can be used to grant full access, read-only access, or access to

        a specific set of endpoints.


        You can generate an OAuth token by visiting the [Apps & API](https://cloud.digitalocean.com/account/api/tokens)

        section of the DigitalOcean control panel for your account.


        An OAuth token functions as a complete authentication request. In effect, it

        acts as a substitute for a username and password pair.


        Because of this, it is absolutely **essential** that you keep your OAuth

        tokens secure. In fact, upon generation, the web interface will only display

        each token a single time in order to prevent the token from being compromised.


        DigitalOcean access tokens begin with an identifiable prefix in order to

        distinguish them from other similar tokens.


        - `dop_v1_` for personal access tokens generated in the control panel

        - `doo_v1_` for tokens generated by applications using [the OAuth flow](https://docs.digitalocean.com/reference/api/oauth-api/)

        - `dor_v1_` for OAuth refresh tokens


        ### Authenticate with a Bearer Authorization Header


        **Serverless Inference:**


        ```

        curl -X POST -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://inference.do-ai.run/v1/chat/completions"

        ```


        **Agent Inference:**


        ```

        curl -X POST -H "Authorization: Bearer $AGENT_ACCESS_KEY" "https://{your-agent-url}.agents.do-ai.run/v1/chat/completions?agent=true"

        ```


        **Note:** Agent Inference APIs use an `agent_access_key` (endpoint access

        key) instead of a DigitalOcean OAuth token. The `agent_access_key` is

        provided when you provision an agent endpoint and is scoped to that

        specific agent. It is not interchangeable with DigitalOcean OAuth tokens

        (`dop_v1_*`, `doo_v1_*`, `dor_v1_*`), which are used with Serverless

        Inference and the control-plane API at `https://api.digitalocean.com`.

        '
x-tagGroups:
- name: Public APIs
  tags:
  - Public APIs Introduction
  - 1-Click Applications
  - Account
  - Actions
  - Add-Ons
  - Action Gateway
  - Action Gateway Data Plane
  - Agent Platform API
  - Apps
  - Billing
  - Block Storage
  - Block Storage Actions
  - BYOIP Prefixes
  - CDN Endpoints
  - Certificates
  - Container Registry
  - Container Registries
  - Databases
  - Dedicated Inference
  - Domain Records
  - Domains
  - Droplet Actions
  - Droplets
  - Droplet Autoscale Pools
  - Firewalls
  - Floating IP Actions
  - Floating IPs
  - Functions
  - Harness Runtime
  - Image Actions
  - Images
  - Insights
  - Kubernetes
  - Load Balancers
  - MicroVMs [Public Preview]
  - Monitoring
  - NFS
  - NFS Actions
  - Organizations
  - Partner Network Connect
  - Project Resources
  - Projects
  - Regions
  - Reserved IP Actions
  - Reserved IPs
  - Reserved IPv6
  - Reserved IPv6 Actions
  - Security
  - Signals
  - Sizes
  - Snapshots
  - Spaces Keys
  - SSH Keys
  - Tags
  - Uptime
  - Vector Databases
  - VPC NAT Gateways
  - VPC Peerings
  - VPC Routes [Public Preview]
  - VPC Subnets [Public Preview]
  - VPCs
- name: Inference APIs
  tags:
  - Inference Introduction
  - Agent Inference
  - Batch Inference
  - Embeddings
  - Serverless Inference