Agentic Platform
Documentation API reference Tools Skills

Tools

Credit Consumption

get_credit_usage MCP

Report how much of this project's agent credit allowance is used, daily and monthly, and who used it.

Report how far through its agent credit allowance the project is, over both windows that carry one: the day and the calendar month, and how this month's consumption splits between the people and service accounts that caused it. The allowance is a project-wide pool shared by every member, not a personal one, and passing it warns rather than blocks: calls keep being served up to a higher ceiling. The per-user breakdown says who drew from that shared pool, as each one's share of the month's consumption. Reading consumption through this agent is itself free and consumes no credits.

Playground

POST
item

No fields.

Schemas

item is what you send, config how the tool behaves, and the response is what you get back.

Item

object
Example
{}

Response

object
Properties
credit_status string required

Where the project stands overall: the worse of the daily and the monthly credit status

Values: healthy warning over blocked

daily CreditWindow required

Information about the daily allowance usage

Type: CreditWindow

monthly CreditWindow required

Information about the monthly allowance usage

Type: CreditWindow

users array required

The users active on this project this month, biggest share first. Each share is a percentage of what the project consumed, not of its allowance, so they sum to 100 rather than to the monthly usage. Clients whose share rounds to nothing are left out, and the list is empty for a project that has spent nothing this month

Items: UserConsumption

summary string required

A paragraph summarizing where usage sits expressed in natural language

Example
{
  "credit_status": "healthy",
  "daily": {
    "usage_percent": 0.0,
    "status": "healthy",
    "resets_at": "string"
  },
  "monthly": {
    "usage_percent": 0.0,
    "status": "healthy",
    "resets_at": "string"
  },
  "users": [
    {
      "client_id": "string",
      "name": "string",
      "share_percent": 0.0,
      "last_activity": "string"
    }
  ],
  "summary": "string"
}

Type Definitions

2 types

These are the available sub-object types that can be used in the properties above.

CreditWindow object
#

How far through its allowance one window is, and where that stands.

usage_percent number | null required

Share of the window's allowance that has been consumed, above 100 once the allowance is passed. Null when there is no allowance to take a share of -- not a statement that calls are blocked

status string required

Where this window's consumption stands, and the only field that says whether calls are still being served: they are refused on ``blocked`` alone

Values: healthy warning over blocked

resets_at string (date-time) required

When the window rolls over and consumption returns to 0

UserConsumption object
#

One client's share of what the project spent this month.

client_id string required

How the agent recorded the caller, usually the email of the Botify user. A client id no user answers to is a service account, and keeps a null name

name string | null required

The Botify user's full name, null when the client id belongs to no user or to one who filled in neither name

share_percent number required

Share of everything the project spent this month that went to this client, as a percentage. A share of the project's own consumption, not of its allowance: these sum to 100 however full the envelope is

last_activity string (date-time) required

When this client last spent any of the project's credits

Endpoints

POST http://agents.botify.com/{organization}/{project}/get_credit_usage/process
POST http://agents.botify.com/{organization}/{project}/get_credit_usage/batch_process
POST http://agents.botify.com/{organization}/{project}/get_credit_usage/async_process
POST http://agents.botify.com/{organization}/{project}/get_credit_usage/async_batch_process

See running a long job in the background for the polling flow.

cURL

curl -X POST "http://agents.botify.com/{organization}/{project}/get_credit_usage/process" \
  -H "Authorization: Bearer $BOTIFY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "item": {}
}'

Over MCP

This tool is exposed as the MCP tool get_credit_usage. An MCP client passes organization, project and item as tool arguments. Set up MCP →

Raw metadata