> ## Documentation Index
> Fetch the complete documentation index at: https://docs.starleads.co/llms.txt
> Use this file to discover all available pages before exploring further.
# Get the consumption breakdown
> Returns the credit consumption of the company owning the API key over the requested range, broken down by channel, month and agent (each agent with its own campaign breakdown). Each axis sums to the total. The range is mandatory, must be ordered and may not span more than 366 days.
## OpenAPI
````yaml GET /Consumption/breakdown
openapi: 3.0.1
info:
title: Starleads public API documentation
description: >
Welcome to the Starleads Public API documentation. This API provides public
access to Starleads services, allowing developers and growth-hackers to
interact with campaign-related data.
***
### Base endpoint
```https://api.starleads.co```
***
### Errors
The API uses standard HTTP status codes to indicate the success or failure
of the API call. In case of failure, the body of the response will be JSON
in the following format:
```
{
"type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
"title": "Bad Request",
"status": 400,
"detail": "No campaign exists with campaignId : 11111111"
}
```
The ```type``` property is a link to a general description of the error
type.
***
### Authentification
Authentication for the API is handled with an API key that must be provided
as a ```X-Api-Key``` header for every request.
**API keys are supposed to be a secret that only the client and server know.
Please remember to not share them with anyone.**
You can find your API keys when authenticated in your Starleads profile
:
version: v1
x-logo:
url: https://api.starleads.co/images/starleads-logo.png
servers: []
security: []
tags:
- name: Agent
description: >-
Manage your AI agent's prompt. These endpoints allow you to read and
update the prompt that drives your agent's behavior during calls.
- name: CampaignField
description: >-
CampaignFields enables users to specify customizable fields within their
campaigns. These fields serve as placeholders (e.g., ```{lastname}```)
that can be dynamically filled with corresponding data when creating
prompts, providing flexibility in tailoring campaign content based on
specific variables.
**Those are the keys of the ```databag``` field of
the request payload to add a new ```CampaignItem``` to a campaign.**
- name: CampaignItem
description: Represents prospects entries related to a campaign
- name: Consumption
description: >-
Track your company's credit consumption. These endpoints expose your
current balance, usage and billing period so you can build budget
monitoring on top of the API.
- name: Subscription
description: >-
Inspect your subscription contract: the plan you are on, your subscription
status, the features currently active and your effective limits. No
pricing information is exposed.
paths:
/Consumption/breakdown:
get:
tags:
- Consumption
summary: Get the consumption breakdown over a date range
description: >-
Returns the credit consumption of the company owning the API key over
the requested range, broken down by channel, month and agent (each agent
with its own campaign breakdown). Each axis sums to the total. The range
is mandatory, must be ordered and may not span more than 366 days.
operationId: GetConsumptionBreakdown
parameters:
- name: X-Api-Key
in: header
description: API key for authentication
required: true
schema:
type: string
- name: From
in: query
required: true
schema:
type: string
description: Start of the consumption range (inclusive)
format: date-time
- name: To
in: query
required: true
schema:
type: string
description: End of the consumption range (inclusive)
format: date-time
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/ConsumptionBreakdown'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
'502':
description: Server Error
'504':
description: Server Error
components:
schemas:
ConsumptionBreakdown:
type: object
properties:
periodFrom:
type: string
description: >-
Start of the range the figures below cover (echoes the requested
'from')
format: date-time
periodTo:
type: string
description: End of the range the figures below cover (echoes the requested 'to')
format: date-time
totalCredits:
type: number
description: >-
Total credits consumed over the requested range. Each axis below
sums to this value.
format: double
byChannel:
type: array
items:
$ref: '#/components/schemas/ChannelConsumption'
description: Consumption split by channel over the whole range
nullable: true
byMonth:
type: array
items:
$ref: '#/components/schemas/MonthlyConsumption'
description: Consumption split by calendar month
nullable: true
byAgent:
type: array
items:
$ref: '#/components/schemas/AgentConsumption'
description: Consumption split by agent, each with its own campaign breakdown
nullable: true
additionalProperties: false
description: >-
Credit consumption broken down by channel, month and agent over a date
range
ProblemDetails:
type: object
properties:
type:
type: string
nullable: true
title:
type: string
nullable: true
status:
type: integer
format: int32
nullable: true
detail:
type: string
nullable: true
instance:
type: string
nullable: true
additionalProperties: {}
ChannelConsumption:
type: object
properties:
channel:
type: string
description: >-
Channel identifier (e.g. voice, sms). "unattributed" carries credits
counted in the total but not attributed to a channel.
nullable: true
credits:
type: number
description: Credits consumed on this channel
format: double
additionalProperties: false
description: Credits consumed on a single channel
MonthlyConsumption:
type: object
properties:
month:
type: string
description: >-
Month in YYYY-MM form. "unattributed" carries credits counted in the
total but not attributed to a month.
nullable: true
credits:
type: number
description: Credits consumed in this month
format: double
additionalProperties: false
description: Credits consumed in a single calendar month
AgentConsumption:
type: object
properties:
agentId:
type: string
description: >-
Agent identifier. Null for a deleted agent or for the unattributed
residual.
nullable: true
nameStatus:
type: string
description: >-
Status of the agent identity: "Resolved" (an agent id was reported),
"Unknown" (credits reported with no agent id — this may be a removed
agent or consumption never attached to one; the billing contract
does not let us tell), or "Unattributed" for the residual entry.
nullable: true
credits:
type: number
description: Credits consumed by this agent
format: double
campaigns:
type: array
items:
$ref: '#/components/schemas/CampaignConsumption'
description: Per-campaign breakdown for this agent
nullable: true
additionalProperties: false
description: Credits consumed by a single agent
CampaignConsumption:
type: object
properties:
campaignId:
type: string
description: Campaign identifier
nullable: true
nameStatus:
type: string
description: >-
Status of the campaign identity: "Resolved" (a campaign id was
reported) or "Unknown" (credits reported with no campaign id).
nullable: true
credits:
type: number
description: Credits consumed by this campaign
format: double
additionalProperties: false
description: Credits consumed by a single campaign
````