---
updatedAt: 2026-08-18T22:07:21.000Z
agentTools:
  projectIndex: https://docs.delivr.ai/llms.txt
---

# Get billing usage summary

Returns your organization's billable usage for a date window: the period total, a per-project breakdown, a per-source breakdown, and a daily trend. The organization is resolved from the API key; no scope parameters are needed.

With no dates, the window defaults to the current calendar month. Dates are day-grained; `end_date` is inclusive. This endpoint is read-only and never metered.


# OpenAPI definition

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "Account",
    "description": "Manage your own organization with the organization API key: validate a key and discover its scope (`whoami`), read or update your organization's profile, read your billing usage (period summary, per-meter rollup, daily trend), and estimate what a quantity would cost at your rates this billing period. Creating organizations,\nprojects, and pixels and managing members use the **Platform Management** (Partner) API.\n\n**Authentication:** organization API key (`X-Api-Key` + `X-Api-Secret`).\n\n**Base URL:** `https://api.delivr.ai`\n",
    "version": "1.0",
    "contact": {
      "name": "Delivr.ai Support",
      "url": "https://delivr.ai"
    }
  },
  "servers": [
    {
      "url": "https://api.delivr.ai",
      "description": "Production"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": [],
      "ApiSecretAuth": []
    }
  ],
  "tags": [
    {
      "name": "Billing",
      "description": "Read your organization's billing usage: period summaries, the per-meter rollup, and the daily trend. These report usage volume, not charges. All reads are scoped to the key's own organization and are free (never metered)."
    }
  ],
  "paths": {
    "/api/v1/billing/usage": {
      "get": {
        "operationId": "getBillingUsage",
        "tags": [
          "Billing"
        ],
        "summary": "Get billing usage summary",
        "description": "Returns your organization's billable usage for a date window: the period total, a per-project breakdown, a per-source breakdown, and a daily trend. The organization is resolved from the API key; no scope parameters are needed.\n\nWith no dates, the window defaults to the current calendar month. Dates are day-grained; `end_date` is inclusive. This endpoint is read-only and never metered.\n",
        "parameters": [
          {
            "name": "start_date",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date"
            },
            "description": "Window start (YYYY-MM-DD, UTC). Defaults to the first of the current month."
          },
          {
            "name": "end_date",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date"
            },
            "description": "Window end (YYYY-MM-DD, UTC), inclusive. Defaults to the end of the current month."
          }
        ],
        "responses": {
          "200": {
            "description": "Usage summary for the window.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BillingUsageResponse"
                }
              }
            }
          },
          "400": {
            "description": "Malformed start_date or end_date."
          },
          "401": {
            "description": "Missing or invalid API key / secret."
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Api-Key",
        "description": "Organization API key (`dlvr_` prefixed), created in the dashboard at `https://app.delivr.ai/{org_id}/settings/api-keys`. Must be paired with the `X-Api-Secret` header."
      },
      "ApiSecretAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Api-Secret",
        "description": "Secret half of the organization API key, paired with `X-Api-Key`. Both headers are required on every request."
      }
    },
    "schemas": {
      "BillingUsageSummary": {
        "type": "object",
        "required": [
          "total_records",
          "total_projects",
          "period_start",
          "period_end"
        ],
        "properties": {
          "total_records": {
            "type": "integer",
            "format": "int64",
            "description": "Total billable records in the window."
          },
          "total_projects": {
            "type": "integer",
            "description": "Number of projects with usage in the window."
          },
          "period_start": {
            "type": "string",
            "format": "date",
            "description": "Window start (inclusive)."
          },
          "period_end": {
            "type": "string",
            "format": "date",
            "description": "Window end (inclusive)."
          }
        }
      },
      "BillingProjectUsage": {
        "type": "object",
        "required": [
          "project_id",
          "project_name",
          "total_records",
          "unique_endpoints",
          "unique_sources"
        ],
        "properties": {
          "project_id": {
            "type": "string",
            "format": "uuid"
          },
          "project_name": {
            "type": "string"
          },
          "total_records": {
            "type": "integer",
            "format": "int64"
          },
          "unique_endpoints": {
            "type": "integer",
            "description": "Distinct endpoints that produced usage for this project."
          },
          "unique_sources": {
            "type": "integer",
            "description": "Distinct sources that produced usage for this project."
          },
          "by_source": {
            "type": "object",
            "additionalProperties": {
              "type": "integer",
              "format": "int64"
            },
            "description": "Records per source for this project."
          }
        }
      },
      "BillingSourceUsage": {
        "type": "object",
        "required": [
          "source",
          "total_records"
        ],
        "properties": {
          "source": {
            "type": "string",
            "description": "The producing service or surface (e.g. an export type)."
          },
          "total_records": {
            "type": "integer",
            "format": "int64"
          }
        }
      },
      "BillingDailyUsage": {
        "type": "object",
        "required": [
          "date",
          "total_records"
        ],
        "properties": {
          "date": {
            "type": "string",
            "format": "date"
          },
          "total_records": {
            "type": "integer",
            "format": "int64"
          }
        }
      },
      "BillingUsageResponse": {
        "type": "object",
        "required": [
          "summary",
          "by_project",
          "by_source",
          "daily_usage"
        ],
        "properties": {
          "summary": {
            "$ref": "#/components/schemas/BillingUsageSummary"
          },
          "by_project": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BillingProjectUsage"
            }
          },
          "by_source": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BillingSourceUsage"
            }
          },
          "daily_usage": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BillingDailyUsage"
            }
          }
        }
      }
    }
  }
}
```