---
updatedAt: 2026-04-21T17:11:35.000Z
agentTools:
projectIndex: https://docs.censys.com/llms.txt
---
# Get organization credit usage
Retrieve credit information for an organization over a specific date range. You must include a start date in your request.
Users with the Platform Admin role can obtain credit usage information for all users in their organization. Other users may only retrieve usage information for their own account.
This endpoint does not cost any credits to execute.
# OpenAPI definition
```json
{
"components": {
"schemas": {
"AuthenticationError": {
"additionalProperties": false,
"properties": {
"error": {
"$ref": "#/components/schemas/AuthenticationErrorDetail",
"description": "Detailed information about the authentication error"
}
},
"type": "object"
},
"AuthenticationErrorDetail": {
"additionalProperties": false,
"properties": {
"code": {
"description": "HTTP status code",
"examples": [
401
],
"format": "int64",
"type": "integer"
},
"message": {
"description": "Human-readable message describing the error occurrence",
"examples": [
"Access credentials are invalid"
],
"type": "string"
},
"reason": {
"description": "Human-readable explanation of the underlying cause of the error",
"examples": [
"Access token is not active"
],
"type": "string"
},
"request": {
"type": "string"
},
"status": {
"description": "HTTP status message associated with the error",
"examples": [
"Unauthorized"
],
"type": "string"
}
},
"type": "object"
},
"CreditUsageReport": {
"additionalProperties": false,
"properties": {
"credits_consumed_by_consumer": {
"additionalProperties": {
"description": "The number of credits consumed by this consumer. The key is the user's email when known, otherwise the user UUID.",
"format": "int64",
"minimum": 0,
"type": "integer"
},
"description": "The breakdown of credits consumed by consumer. This may not be present if the report is generated for a specific user.",
"examples": [
{
"user@example.com": 3000
}
],
"type": "object"
},
"credits_consumed_by_source": {
"$ref": "#/components/schemas/SourceUsageBreakdown",
"description": "The breakdown of credits consumed by source."
},
"end_time": {
"description": "The end time of the window for this report.",
"format": "date-time",
"type": "string"
},
"granularity": {
"default": "daily",
"description": "The granularity of the report.",
"enum": [
"daily",
"monthly"
],
"examples": [
"daily"
],
"type": "string"
},
"periods": {
"description": "The periods of the report (i.e. time buckets).",
"items": {
"$ref": "#/components/schemas/CreditUsageReportPeriod"
},
"type": [
"array",
"null"
]
},
"start_time": {
"description": "The start time of the window for this report.",
"format": "date-time",
"type": "string"
},
"total_added": {
"description": "The total amount of credits added during the report period.",
"format": "int64",
"type": "integer"
},
"total_consumed": {
"description": "The total amount of credits consumed during the report period.",
"format": "int64",
"type": "integer"
},
"total_expired": {
"description": "The total amount of credits expired during the report period.",
"format": "int64",
"type": "integer"
},
"transaction_count": {
"description": "The total number of transactions during the report period.",
"format": "int64",
"type": "integer"
}
},
"required": [
"start_time",
"end_time",
"granularity",
"total_consumed",
"total_added",
"total_expired",
"transaction_count",
"periods",
"credits_consumed_by_source"
],
"type": "object"
},
"CreditUsageReportPeriod": {
"additionalProperties": false,
"properties": {
"credits_added": {
"description": "The total amount of credits added during the report period.",
"format": "int64",
"type": "integer"
},
"credits_consumed": {
"description": "The total amount of credits consumed during the report period.",
"format": "int64",
"type": "integer"
},
"credits_expired": {
"description": "The total amount of credits expired during the report period.",
"format": "int64",
"type": "integer"
},
"end_date": {
"description": "The end date of the window for this report period.",
"format": "date-time",
"type": "string"
},
"start_date": {
"description": "The start date of the window for this report period.",
"format": "date-time",
"type": "string"
},
"transaction_count": {
"description": "The total number of transactions during the report period.",
"format": "int64",
"type": "integer"
}
},
"required": [
"start_date",
"end_date",
"credits_consumed",
"credits_added",
"credits_expired",
"transaction_count"
],
"type": "object"
},
"ErrorDetail": {
"additionalProperties": false,
"properties": {
"location": {
"description": "Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id'",
"type": "string"
},
"message": {
"description": "Error message text",
"type": "string"
},
"value": {
"description": "The value at the given location"
}
},
"type": "object"
},
"ErrorModel": {
"additionalProperties": false,
"properties": {
"detail": {
"description": "A human-readable explanation specific to this occurrence of the problem.",
"examples": [
"Property foo is required but is missing."
],
"type": "string"
},
"errors": {
"description": "Optional list of individual error details",
"items": {
"$ref": "#/components/schemas/ErrorDetail"
},
"type": [
"array",
"null"
]
},
"instance": {
"description": "A URI reference that identifies the specific occurrence of the problem.",
"examples": [
"https://example.com/error-log/abc123"
],
"format": "uri",
"type": "string"
},
"status": {
"description": "HTTP status code",
"examples": [
400
],
"format": "int64",
"type": "integer"
},
"title": {
"description": "A short, human-readable summary of the problem type. This value should not change between occurrences of the error.",
"examples": [
"Bad Request"
],
"type": "string"
},
"type": {
"default": "about:blank",
"description": "A URI reference to human-readable documentation for the error.",
"examples": [
"https://example.com/errors/example"
],
"format": "uri",
"type": "string"
}
},
"type": "object"
},
"ResponseEnvelopeCreditUsageReport": {
"additionalProperties": false,
"properties": {
"result": {
"$ref": "#/components/schemas/CreditUsageReport"
}
},
"type": "object"
},
"SourceUsageBreakdown": {
"additionalProperties": false,
"properties": {
"api": {
"description": "The amount of credits consumed through the Platform API.",
"format": "int64",
"type": "integer"
},
"auto_replenishment": {
"description": "The amount of credits consumed through auto-replenishment.",
"format": "int64",
"type": "integer"
},
"other": {
"description": "The amount of credits consumed through other operations.",
"format": "int64",
"type": "integer"
},
"ui": {
"description": "The amount of credits consumed through the Platform UI.",
"format": "int64",
"type": "integer"
}
},
"required": [
"ui",
"api"
],
"type": "object"
}
},
"securitySchemes": {
"PersonalAccessToken": {
"description": "Your Censys personal access token. These are managed in your [Account Settings](https://accounts.censys.io/settings/personal-access-tokens)",
"scheme": "bearer",
"type": "http"
}
}
},
"info": {
"contact": {
"email": "support@censys.com",
"name": "Censys Inc.",
"url": "https://censys.com"
},
"title": "Censys Platform API",
"version": "1.0.151"
},
"openapi": "3.1.0",
"paths": {
"/v3/accounts/organizations/{organization_id}/credits/usage": {
"get": {
"description": "Retrieve credit information for an organization over a specific date range. You must include a start date in your request.
Users with the Platform Admin role can obtain credit usage information for all users in their organization. Other users may only retrieve usage information for their own account.
This endpoint does not cost any credits to execute.",
"operationId": "v3-accountmanagement-org-credits-usage",
"parameters": [
{
"description": "The ID of a Censys organization. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information.",
"in": "path",
"name": "organization_id",
"required": true,
"schema": {
"description": "The ID of a Censys organization. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information.",
"examples": [
"11111111-2222-3333-4444-555555555555"
],
"format": "uuid",
"type": "string"
}
},
{
"description": "The date for the credit usage report in YYYY-MM-DD format (e.g., 2025-11-06). This field is deprecated and will be removed in a future version. Use start_date and end_date instead. The date must be on or after 2025-01-01 (the earliest date available for credit usage reports).",
"explode": false,
"in": "query",
"name": "date",
"schema": {
"deprecated": true,
"description": "The date for the credit usage report in YYYY-MM-DD format (e.g., 2025-11-06). This field is deprecated and will be removed in a future version. Use start_date and end_date instead. The date must be on or after 2025-01-01 (the earliest date available for credit usage reports).",
"examples": [
"2025-11-01"
],
"type": "string"
}
},
{
"description": "The start date for the credit usage report in YYYY-MM-DD format (e.g., 2025-11-01). Must be on or after 2025-01-01 (the earliest date available for credit usage reports).",
"explode": false,
"in": "query",
"name": "start_date",
"schema": {
"description": "The start date for the credit usage report in YYYY-MM-DD format (e.g., 2025-11-01). Must be on or after 2025-01-01 (the earliest date available for credit usage reports).",
"examples": [
"2025-11-01"
],
"format": "date",
"type": "string"
}
},
{
"description": "The end date for the credit usage report in YYYY-MM-DD format (e.g., 2025-12-01). If omitted, will default to today's date. The date range (end_date - start_date) cannot exceed 365 days (1 year).",
"explode": false,
"in": "query",
"name": "end_date",
"schema": {
"description": "The end date for the credit usage report in YYYY-MM-DD format (e.g., 2025-12-01). If omitted, will default to today's date. The date range (end_date - start_date) cannot exceed 365 days (1 year).",
"examples": [
"2025-12-01"
],
"format": "date",
"type": "string"
}
},
{
"description": "Whether to break down credit usage on a daily or monthly basis.",
"explode": false,
"in": "query",
"name": "granularity",
"required": true,
"schema": {
"default": "daily",
"description": "Whether to break down credit usage on a daily or monthly basis.",
"enum": [
"daily",
"monthly"
],
"examples": [
"daily"
],
"type": "string"
}
},
{
"description": "Whether to include a breakdown of individual users' consumption in the credit usage report.",
"explode": false,
"in": "query",
"name": "include_consumer_breakdown",
"schema": {
"default": false,
"description": "Whether to include a breakdown of individual users' consumption in the credit usage report.",
"type": "boolean"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ResponseEnvelopeCreditUsageReport"
}
}
},
"description": "OK",
"headers": {
"Content-Type": {
"schema": {
"type": "string"
}
},
"X-Request-ID": {
"schema": {
"type": "string"
}
}
}
},
"400": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ErrorModel"
}
}
},
"description": "Invalid date format"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AuthenticationError"
}
}
},
"description": "Request does not contain a valid Authorization token"
},
"403": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ErrorModel"
}
}
},
"description": "User does not have permission to access this data"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ErrorModel"
}
}
},
"description": "Organization not found"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ErrorModel"
}
}
},
"description": "Invalid organization ID or date"
},
"500": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ErrorModel"
}
}
},
"description": "Internal server error"
}
},
"security": [
{
"PersonalAccessToken": []
}
],
"summary": "Get organization credit usage",
"tags": [
"Account Management"
],
"x-speakeasy-name-override": "GetOrganizationCreditUsage"
}
}
},
"servers": [
{
"description": "The Censys Platform API",
"url": "https://api.platform.censys.io"
}
],
"tags": [
{
"description": "Endpoints related to the Account Management product",
"name": "Account Management"
}
],
"x-readme": {
"parameter-ordering": [
"path",
"body",
"query",
"cookie",
"form",
"header"
],
"samples-languages": [
"shell",
"python",
"go",
"javascript",
"java"
]
},
"x-speakeasy-globals": {
"parameters": [
{
"in": "query",
"name": "organization_id",
"schema": {
"type": "string"
}
}
]
}
}
```