---
title: Credits Usage API
version: 1.0.0
description: Retrieve the remaining and consumed API credit balances for the authenticated organization. Returns subscription-plan credits, subscription surcharge (overage) credits, and one-off credit purchases as separate balances, each with allowed and used counts. Only an organization admin API key can call this endpoint; all other keys receive a 403. There are no optional data modules for this endpoint — the response always includes the full credit breakdown.
openapi: 3.1.1
servers:
  - https://api.apifreaks.com/v1.0
paths: 1
operations: 1
schemas: 2
---

## Table of Contents

- [Credits Usage API v1.0.0](#credits-usage-api-v100)
  - [Authentication](#authentication)
  - [General APIs](#general-apis)
    - [getCreditsUsage](#getcreditsusage)
      - [Parameters](#parameters)
      - [Responses](#responses)
  - [Schemas](#schemas)
    - [CreditsUsageResponse](#creditsusageresponse)
    - [ErrorResponse](#errorresponse)



# Credits Usage API v1.0.0

Retrieve the remaining and consumed API credit balances for the authenticated organization. Returns subscription-plan credits, subscription surcharge (overage) credits, and one-off credit purchases as separate balances, each with allowed and used counts. Only an organization admin API key can call this endpoint; all other keys receive a 403. There are no optional data modules for this endpoint — the response always includes the full credit breakdown.

Base URLs:

* [https://api.apifreaks.com/v1.0](https://api.apifreaks.com/v1.0)

## Authentication

* API Key (ApiKeyAuthHeader)
    - Parameter Name: **X-apiKey**, in: header. Pass your API key via the X-apiKey request header.

* API Key (ApiKeyAuthQuery)
    - Parameter Name: **apiKey**, in: query. Pass your API key via the apiKey query parameter.

## General APIs

### getCreditsUsage

`GET /credits/usage/info`

*Get remaining and consumed API credit balances for the organization*

Returns subscription, subscription-surcharge, and one-off credit balances for the authenticated organization's account.

#### Parameters

|Name|In|Type|Required|Description|
|---|---|---|---|---|
|format|query|string|false|Format of the response. Possible values: json, xml.|

##### Enumerated Values

|Parameter|Value|
|---|---|
|format|json|
|format|xml|

> Example responses

> Successful response with credit balances

```json
{
  "apiKey": "demo",
  "userStatus": "active",
  "subActive": true,
  "subStatus": "active",
  "subAllowedCredits": 10000,
  "subUsedCredits": 2500,
  "subSurchargeStatus": "none",
  "subSurchargeAllowedCredits": 0,
  "subSurchargeUsedCredits": 0,
  "subSurchargeAllowed": false,
  "oneOffCreditsActive": true,
  "oneOffAllowedCredits": 5000,
  "oneOffUsedCredits": 1000
}
```

> Forbidden — Caller is not an organization admin

```json
{
  "timestamp": "2026-07-27T10:23:16.548Z",
  "path": "/v1.0/credits/usage/info",
  "status": 403,
  "error": "API Access Exception",
  "message": "You need to be organization admin to access this endpoint."
}
```

#### Responses

|Status|Meaning|Description|Schema|
|---|---|---|---|
|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|Successful response with credit balances|[CreditsUsageResponse](#creditsusageresponse)|
|403|[Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3)|Forbidden — Caller is not an organization admin|[ErrorResponse](#errorresponse)|

#### Response Headers

|Status|Header|Type|Format|Description|
|---|---|---|---|---|
|200|X-AF-Credits-Cost|integer||Specifies the number of credits consumed by the current request.|
|403|X-AF-Credits-Cost|integer||Specifies the number of credits consumed by the current request.|

To perform this operation, you must be authenticated by means of one of the following methods:
ApiKeyAuthHeader, ApiKeyAuthQuery

## Schemas

### CreditsUsageResponse

Credit balances for the organization's subscription, subscription surcharge, and one-off purchases.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|apiKey|string|true|none|The API key the credit balances belong to.|
|userStatus|string|true|none|Status of the user account.|
|subActive|boolean|false|none|Whether a subscription plan is currently active. Null if the account has no subscription.|
|subStatus|string|false|none|Status of the subscription credits. Null if the account has no subscription.|
|subAllowedCredits|integer|false|none|Total credits allowed under the subscription plan. Null if the account has no subscription.|
|subUsedCredits|integer|false|none|Credits consumed under the subscription plan. Null if the account has no subscription.|
|subSurchargeStatus|string|false|none|Status of the subscription surcharge (overage) credits. Null if the account has no subscription.|
|subSurchargeAllowedCredits|integer|false|none|Total surcharge credits allowed. Null if the account has no subscription.|
|subSurchargeUsedCredits|integer|false|none|Surcharge credits consumed. Null if the account has no subscription.|
|subSurchargeAllowed|boolean|false|none|Whether surcharge (overage) usage is allowed on the subscription. Null if the account has no subscription.|
|oneOffCreditsActive|boolean|true|none|Whether the account has active one-off (pay-as-you-go) credits.|
|oneOffAllowedCredits|integer|true|none|Total one-off credits purchased.|
|oneOffUsedCredits|integer|true|none|One-off credits consumed.|

##### Enumerated Values

|Property|Value|
|---|---|
|userStatus|active|
|userStatus|inactive|
|userStatus|deleted|
|subStatus|active|
|subStatus|overdue|
|subStatus|cancelled|
|subStatus|deactivated|
|subStatus|null|
|subSurchargeStatus|none|
|subSurchargeStatus|payment_added|
|subSurchargeStatus|payment_cleared|
|subSurchargeStatus|null|

### ErrorResponse

Standard error envelope returned by the API on failed requests.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|error|string|false|none|Short error category or exception type.|
|message|string|true|none|Human-readable error message describing the failure.|
|path|string|false|none|API endpoint path that produced the error.|
|status|integer|false|none|HTTP status code returned with the error.|
|timestamp|string(date-time)|false|none|Timestamp when the error occurred (ISO 8601).|