Skip to main content
POST
/
v1
/
credits
/
aggregation
Get Credit Aggregation
curl --request POST \
  --url https://api.explorium.ai/v1/credits/aggregation \
  --header 'Content-Type: application/json' \
  --header 'api_key: <api-key>' \
  --data '
{
  "from_date": "<string>",
  "to_date": "<string>",
  "mode": "timely",
  "request_context": null,
  "resolution": "hour",
  "timezone": "UTC"
}
'
{
  "response_context": {
    "correlation_id": "5618d686ecb849fda660c3023acf3120",
    "request_status": "success",
    "time_took_in_seconds": 0.245
  },
  "from_date": "2025-08-23T00:00:00Z",
  "to_date": "2025-08-24T00:00:00Z",
  "resolution": "hour",
  "timezone": "UTC",
  "total_credits": 1245,
  "aggregations": [
    {
      "timestamp": "2025-08-23T00:00:00Z",
      "hour": "00:00",
      "date": "2025-08-23",
      "credits": 45
    },
    {
      "timestamp": "2025-08-23T01:00:00Z",
      "hour": "01:00",
      "date": "2025-08-23",
      "credits": 52
    },
    {
      "timestamp": "2025-08-23T13:00:00Z",
      "hour": "13:00",
      "date": "2025-08-23",
      "credits": 89
    }
  ]
}

​
Overview

The Credit Consumption Aggregation endpoint provides detailed analytics on credit usage across your account. Query consumption data by time periods (hourly, daily, monthly) or by API endpoint to understand usage patterns and optimize your credit allocation.

​
Authentication

Include your account API key in the request header: 
api_key: YOUR_API_KEY

​
Request Body

​
from_date
string
required
Start date and time for the aggregation period (ISO 8601 format)Example: "2025-08-23T00:00:00Z"
​
to_date
string
required
End date and time for the aggregation period (ISO 8601 format)Example: "2025-08-24T00:00:00Z"
​
resolution
string
required
Time resolution for aggregating credit dataAllowed values: hour | day | monthDate range limits:
  • hour: Maximum 7 days
  • day: Maximum 60 days
  • month: Maximum 2 years
​
timezone
string
Timezone for the aggregation (default: UTC)Example: "America/New_York"

​
Response

Returns a JSON object containing aggregated credit consumption data:
​
response_context
object
Metadata about the API response
​
from_date
string
Start date of the aggregation period
​
to_date
string
End date of the aggregation period
​
resolution
string
Time resolution used for aggregation
​
timezone
string
Timezone applied to the aggregation
​
total_credits
integer
Total credits consumed during the specified period
​
aggregations
array
Array of aggregated credit consumption data points

​
Examples

curl --request POST \
  --url https://api.explorium.ai/v1/credits/aggregation \
  --header 'Content-Type: application/json' \
  --header 'api_key: YOUR_API_KEY' \
  --data '{
    "from_date": "2025-08-23T00:00:00Z",
    "to_date": "2025-08-24T00:00:00Z",
    "resolution": "hour"
  }'

{
  "response_context": {
    "correlation_id": "5618d686ecb849fda660c3023acf3120",
    "request_status": "success",
    "time_took_in_seconds": 0.245
  },
  "from_date": "2025-08-23T00:00:00Z",
  "to_date": "2025-08-24T00:00:00Z",
  "resolution": "hour",
  "timezone": "UTC",
  "total_credits": 1245,
  "aggregations": [
    {
      "timestamp": "2025-08-23T00:00:00Z",
      "hour": "00:00",
      "date": "2025-08-23",
      "credits": 45
    },
    {
      "timestamp": "2025-08-23T01:00:00Z",
      "hour": "01:00",
      "date": "2025-08-23",
      "credits": 52
    },
    {
      "timestamp": "2025-08-23T13:00:00Z",
      "hour": "13:00",
      "date": "2025-08-23",
      "credits": 89
    }
  ]
}

​
Error Responses

{
  "response_context": {
    "correlation_id": "error123456789",
    "request_status": "failure",
    "time_took_in_seconds": 0.012
  },
  "error": {
    "code": "INVALID_DATE_RANGE",
    "message": "The from_date must be before to_date",
    "details": {
      "from_date": "2025-08-24T00:00:00Z",
      "to_date": "2025-08-23T00:00:00Z"
    }
  }
}

​
Use Cases

Monitoring Credit Usage Patterns Track how your credit consumption varies throughout the day, week, or month to identify peak usage times and optimize your API call scheduling. Budget Planning Use monthly aggregations to understand long-term trends and plan your credit allocation for upcoming periods. Anomaly Detection Monitor hourly or daily consumption to quickly identify unexpected spikes in usage that may indicate issues or opportunities for optimization. Reporting and Analytics Generate detailed consumption reports for internal stakeholders or integrate with your own analytics dashboards for comprehensive visibility.

Authorizations

​
api_key
string
header
required

Body

application/json
​
from_date
string
required

ISO 8601 datetime string for start date

​
to_date
string
required

ISO 8601 datetime string for end date

​
mode
enum<string>
required

Aggregation mode

Available options:
timely,
endpoints
​
request_context
Request Context · object
Example:

null

​
resolution
enum<string>

Aggregation resolution (required for timely mode, optional for endpoints mode)

Available options:
hour,
day,
month
​
timezone
string
default:UTC

Timezone for aggregation, defaults to UTC

Response

Successful Response

This is base response model for all responses in partner service.

​
response_context
ResponseContext · object
required
​
from_date
string
required

ISO 8601 datetime string for start date

​
to_date
string
required

ISO 8601 datetime string for end date

​
mode
string
required

Aggregation mode

​
timezone
string
required

Timezone used for aggregation

​
total_credits
integer
required

Total credits consumed in the period

​
aggregations
Aggregations · object[]
required

Array of aggregation data points

​
resolution
enum<string>

Aggregation resolution (not applicable for endpoints mode)

Available options:
hour,
day,
month