GET /organization/usage

Admin endpoint to retrieve usage statistics and metrics for your organization with date range filtering and optional daily breakdown.

https://api.webcrawlerapi.com/v2/organization/usage

Format: JSON Method: GET

Request

Available query parameters:

from - (optional) Start date for usage period in YYYY-MM-DD format (e.g., "2024-01-01"). Default: 30 days before to date
to - (optional) End date for usage period in YYYY-MM-DD format (e.g., "2024-01-31"). Default: current date (today)
include_daily - (optional) Include daily breakdown in response. Set to true or 1 to enable. Default: false

Constraints:

Date range cannot exceed 1 year (365 days)
from date must be before or equal to to date
Both dates must be in YYYY-MM-DD format

Authentication:

Requires admin API key in Authorization header
Format: Bearer YOUR_ADMIN_API_KEY

Example with parameters:

curl --request GET \
  --url 'https://api.webcrawlerapi.com/v2/organization/usage?from=2024-01-01&to=2024-01-31&include_daily=true' \
  --header 'Authorization: Bearer YOUR_ADMIN_API_KEY'

Example with defaults (last 30 days):

curl --request GET \
  --url 'https://api.webcrawlerapi.com/v2/organization/usage' \
  --header 'Authorization: Bearer YOUR_ADMIN_API_KEY'

Response

The response contains aggregated usage statistics for the authenticated organization:

from - Start date of the reporting period (YYYY-MM-DD)
to - End date of the reporting period (YYYY-MM-DD)
org_id - Your organization identifier
cost_usd - Total cost in USD for the period
requests - Total number of API requests for the period
data - (optional) Array of daily usage breakdowns (only included if include_daily=true)

Daily Usage Object (in data array):

date - Date in YYYY-MM-DD format
cost_usd - Cost in USD for that day (0.0 if no usage)
requests - Number of requests for that day (0 if no usage)

Note: The daily breakdown includes all days in the specified range, even days with no usage (shown as zeros).

Example Response (without daily breakdown)

{
  "from": "2024-01-01",
  "to": "2024-01-31",
  "org_id": "clwgv3ywz000hsy99lwbk7q18",
  "cost_usd": 45.23,
  "requests": 2250
}

Example Response (with daily breakdown)

{
  "from": "2024-01-01",
  "to": "2024-01-05",
  "org_id": "clwgv3ywz000hsy99lwbk7q18",
  "cost_usd": 4.56,
  "requests": 227,
  "data": [
    {
      "date": "2024-01-01",
      "cost_usd": 1.52,
      "requests": 75
    },
    {
      "date": "2024-01-02",
      "cost_usd": 1.48,
      "requests": 74
    },
    {
      "date": "2024-01-03",
      "cost_usd": 0.0,
      "requests": 0
    },
    {
      "date": "2024-01-04",
      "cost_usd": 1.56,
      "requests": 78
    },
    {
      "date": "2024-01-05",
      "cost_usd": 0.0,
      "requests": 0
    }
  ]
}

Error Responses

400 Bad Request - Invalid parameters (wrong format, or date range exceeds 1 year)

{
  "error_code": "invalid_request",
  "error_message": "Invalid 'from' date format. Expected YYYY-MM-DD"
}

401 Unauthorized - Invalid or missing API key

{
  "error_code": "unauthorized",
  "error_message": "Unauthorized"
}

404 Not Found - API key does not belong to an admin organization

500 Internal Server Error - Server-side error occurred while retrieving data

{
  "error_code": "internal_server_error",
  "error_message": "Failed to retrieve usage data"
}

Use Cases

Get Last 30 Days Usage (Default)

# Get last 30 days with no parameters
curl --request GET \
  --url 'https://api.webcrawlerapi.com/v2/organization/usage' \
  --header 'Authorization: Bearer YOUR_ADMIN_API_KEY'

Monitor Monthly Usage

# Get specific month's usage
curl --request GET \
  --url 'https://api.webcrawlerapi.com/v2/organization/usage?from=2024-01-01&to=2024-01-31' \
  --header 'Authorization: Bearer YOUR_ADMIN_API_KEY'

Analyze Daily Patterns

# Get weekly usage with daily breakdown
curl --request GET \
  --url 'https://api.webcrawlerapi.com/v2/organization/usage?from=2024-01-01&to=2024-01-07&include_daily=true' \
  --header 'Authorization: Bearer YOUR_ADMIN_API_KEY'

Generate Annual Reports

# Get full year usage (maximum allowed range)
curl --request GET \
  --url 'https://api.webcrawlerapi.com/v2/organization/usage?from=2024-01-01&to=2024-12-31' \
  --header 'Authorization: Bearer YOUR_ADMIN_API_KEY'

Notes

If no date parameters are provided, the endpoint returns the last 30 days of usage by default
Data is retrieved from pre-aggregated statistics table for optimal performance
Costs are calculated based on job items processed, not jobs created
All timestamps are in UTC
Daily breakdown is optional to optimize performance for large date ranges
Daily breakdown includes all days in the range - days with no usage will show zero cost and zero requests
The endpoint returns data only for the authenticated organization (API key owner)
Costs are converted from internal credits to USD (1 USD = 1,000,000 credits)

GET /organization/usage

On this page