Credit Usage

The usage endpoint returns the remaining credit balance for one client. Use it to check the available allowance before submitting incidents.

Without a clientId, the endpoint reports the balance for the client that owns the API key. A parent or reseller key can pass clientId to check a managed sub-client that the key is authorised for.

Endpoint

GET /v1/usage

Parameters

Parameter	Type	Required	Description
clientId	string	No	Return the balance for this client instead of the API key owner. The client must be one the key is authorised for.

Authorisation

Requesting a clientId your API key is not authorised for returns 401 with Unauthorized. Please ensure client ID is valid.. Use the Clients endpoint to list the clients available to your key.

Remaining Credits

The remainingCredits field can contain one of three values:

Value	Meaning
number	Credits remaining for a metered client. 0 means the allowance is depleted.
"unlimited"	The client has an unlimited allowance.
null	The client is not using the credit system. This does not mean the client has zero credits.

Request Example

cURLPythonNode.js

# The API key owner's balance
curl -X GET 'https://capi.phishfort.com/v1/usage' \
  -H 'accept: application/json' \
  -H 'x-api-key: YOUR_API_KEY'

# An authorised sub-client's balance
curl -X GET -G 'https://capi.phishfort.com/v1/usage' \
  -H 'accept: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d 'clientId=0Xp5voyA4y5xYNoufOVC'

import requests

response = requests.get(
    "https://capi.phishfort.com/v1/usage",
    headers={
        "accept": "application/json",
        "x-api-key": "YOUR_API_KEY",
    },
    params={
        "clientId": "0Xp5voyA4y5xYNoufOVC",
    },
)
print(response.json())

const params = new URLSearchParams({
  clientId: "0Xp5voyA4y5xYNoufOVC",
});

const response = await fetch(
  `https://capi.phishfort.com/v1/usage?${params}`,
  {
    headers: {
      accept: "application/json",
      "x-api-key": "YOUR_API_KEY",
    },
  }
);
const data = await response.json();
console.log(data);

Omit clientId in any example to retrieve the API key owner's balance.

Response Example

The data field is a single UsageStructure.

{
    "message": "success",
    "data": {
        "clientId": "0Xp5voyA4y5xYNoufOVC",
        "clientName": "Example Client",
        "remainingCredits": 250
    }
}

An account with an unlimited allowance returns "unlimited":

{
    "message": "success",
    "data": {
        "clientId": "0Xp5voyA4y5xYNoufOVC",
        "clientName": "Example Client",
        "remainingCredits": "unlimited"
    }
}

Errors

Status	Message	Cause
401	Unauthorized. Please ensure client ID is valid.	The requested clientId is not one your API key represents.
503	Credit usage data is not available.	Credit usage data could not be retrieved. Retry the request shortly.