Get API Pro Usage

Description

Returns the API Pro usage for the current month, allowing programmatic tracking of the number of requests (hits) made and their respective costs.

Usage is presented separately for daytime and nighttime periods, along with the total accumulated values for the period. The response also provides the currency used and the financial usage limit (costLimit) configured for the scope of the key used in the request.

The query respects the scope of the access key:

General Admin key: returns usage belonging to the General Admin scope.

Branch key: returns only usage belonging to the respective branch scope.

🚧 Notes
The returned usage corresponds to the current month.
API Pro usage is calculated considering the applicable costs for daytime and nighttime hits.
The financial limit is independent between different scopes. Usage generated by keys registered under General Admin is accounted for within the General Admin scope, while usage generated by a branch key is accounted for within the respective branch scope.
The costLimit field represents the financial limit configured for the queried scope.
The financial limit is optional. When configured, it is used to control the maximum API Pro usage cost for the period.
When the accumulated cost reaches the configured limit, the keys linked to the respective scope are blocked from generating additional API Pro usage.
After the limit is reached and the key is blocked, this endpoint can no longer be queried using the blocked key. Requests will return HTTP 401 with the API_COST_LIMIT_REACHED code.
Usage and blocking are reset at the beginning of a new month, while the configured limit remains in effect for the new period.

📤 Response Structure

The response provides the considered period, currency, API Pro usage separated into daytime and nighttime periods, total usage, and the configured financial limit.

Field	Type	Description
`period`	object	Object containing the period considered for usage calculation. See below.
`currency`	string	Currency used for usage costs and the financial limit.
`usage`	object	Object containing the number of hits and accumulated costs for the period. See below.
`costLimit`	number	API Pro financial usage limit configured for the scope of the key used.

🧩 `period` Object Structure

Field	Type	Description
`start`	date-time	Start date and time of the period considered for usage calculation in the current month.
`end`	date-time	End date and time of the period considered for usage calculation.

🧩 `usage` Object Structure

Field	Type	Description
`daytime`	object	Accumulated usage during the daytime period.
`nighttime`	object	Accumulated usage during the nighttime period.
`total`	object	Total accumulated usage considering both daytime and nighttime periods.

🧩 `daytime`, `nighttime`, and `total` Object Structure

Field	Type	Description
`hits`	int32	Number of requests (hits) counted for the respective period. In the `total` object, it represents the sum of daytime and nighttime hits.
`cost`	number	Accumulated cost of requests for the respective period. In the `total` object, it represents the total accumulated cost.

💰 Currency

The currency used to display usage and the financial limit varies according to the customer's market:

Market	`currency`
Brazil	`BRL`
Applicable LATAM markets	`USD`

⚠️ Usage Limit Reached

When the accumulated cost reaches 100% of the configured costLimit, the keys linked to the respective scope are blocked.

From that point onward, new requests made with the blocked key, including requests to this endpoint, will return:

HTTP 401

{
  "error": {
    "code": "API_COST_LIMIT_REACHED",
    "message": "The configured API usage cost limit has been reached."
  }
}

NOTE. While the key remains active, this endpoint can be used to monitor usage and compare usage.total.cost against the configured costLimit.

Basic Auth

Send your HTTP requests with an

Authorization

header that contains the word Basic followed by a space and a base64-encoded string username:password

Example:

Authorization: Basic *****************

Responses

🟢200

application/json

Success

Body

Example

{
    "period": {
        "start": "2019-08-24T14:15:22.123Z",
        "end": "2019-08-24T14:15:22.123Z"
    },
    "currency": "string",
    "usage": {
        "daytime": {
            "hits": 0,
            "cost": 0
        },
        "nighttime": {
            "hits": 0,
            "cost": 0
        },
        "total": {
            "hits": 0,
            "cost": 0
        }
    },
    "costLimit": 0
}

🟠400

Get API Pro usage of the current month (hits and costs by period) and the configured cost limit

Get API Pro Usage

Description

📤 Response Structure

🧩 `period` Object Structure

🧩 `usage` Object Structure

🧩 `daytime`, `nighttime`, and `total` Object Structure

💰 Currency

⚠️ Usage Limit Reached

Request

Request Code Samples

Responses

Get API Pro usage of the current month (hits and costs by period) and the configured cost limit

Get API Pro Usage#

Description#

📤 Response Structure#

🧩 period Object Structure#

🧩 usage Object Structure#

🧩 daytime, nighttime, and total Object Structure#

💰 Currency#

⚠️ Usage Limit Reached#

Request

Request Code Samples

Responses

Get API Pro Usage

Description

📤 Response Structure

🧩 `period` Object Structure

🧩 `usage` Object Structure

🧩 `daytime`, `nighttime`, and `total` Object Structure

💰 Currency

⚠️ Usage Limit Reached