Credits

The Credits API allows you to check credit balances, view usage history, and manage credit allocations.

Get Organization Balance

Retrieve the current credit balance for your organization.

GET /v1/credits/balance

Required scope: credits:read

Example Request

curl -X GET "https://api.agent.net.ai/v1/credits/balance" \
  -H "Authorization: Bearer <token>"

Example Response

{
  "data": {
    "organization_id": "org_abc123",
    "balance": 4250,
    "allocated": 3800,
    "unallocated": 450,
    "auto_replenish": true,
    "replenish_threshold": 500,
    "replenish_amount": 5000,
    "updated_at": "2026-04-12T10:00:00Z"
  }
}

Response Fields

Field	Type	Description
`balance`	integer	Total credits remaining in the organization
`allocated`	integer	Credits assigned to users and departments
`unallocated`	integer	Credits available for allocation
`auto_replenish`	boolean	Whether auto-replenishment is enabled
`replenish_threshold`	integer	Balance level that triggers auto-replenishment
`replenish_amount`	integer	Number of credits added on replenishment

Get User Balance

Retrieve the credit balance for a specific user.

GET /v1/credits/users/{user_id}/balance

Required scope: credits:read

Path Parameters

Parameter	Type	Description
`user_id`	string	The user identifier

Example Request

curl -X GET "https://api.agent.net.ai/v1/credits/users/user_abc123/balance" \
  -H "Authorization: Bearer <token>"

Example Response

{
  "data": {
    "user_id": "user_abc123",
    "balance": 320,
    "monthly_limit": 500,
    "used_this_month": 180,
    "rollover_enabled": false,
    "updated_at": "2026-04-12T10:00:00Z"
  }
}

Get Usage History

Retrieve credit usage history with filtering and aggregation options.

GET /v1/credits/usage

Required scope: credits:read

Query Parameters

Parameter	Type	Default	Description
`limit`	integer	50	Number of records per page (max 200)
`cursor`	string	—	Pagination cursor
`user_id`	string	—	Filter by user
`agent_id`	string	—	Filter by agent
`date_from`	string	—	Start date (ISO 8601)
`date_to`	string	—	End date (ISO 8601)
`group_by`	string	—	Aggregate results: `day`, `week`, `month`, `user`, `agent`

Example Request

curl -X GET "https://api.agent.net.ai/v1/credits/usage?date_from=2026-04-01&group_by=day" \
  -H "Authorization: Bearer <token>"

Example Response

{
  "data": [
    {
      "date": "2026-04-01",
      "total_credits": 145,
      "query_count": 52,
      "unique_users": 8,
      "breakdown_by_model": {
        "Fast": 78,
        "Smart": 52,
        "Premium": 15
      }
    },
    {
      "date": "2026-04-02",
      "total_credits": 132,
      "query_count": 47,
      "unique_users": 7,
      "breakdown_by_model": {
        "Fast": 65,
        "Smart": 47,
        "Premium": 20
      }
    }
  ],
  "meta": {
    "total_credits": 277,
    "total_queries": 99,
    "date_range": {
      "from": "2026-04-01",
      "to": "2026-04-02"
    }
  }
}

Detailed Usage (Without Grouping)

When no group_by parameter is specified, individual usage records are returned:

{
  "data": [
    {
      "id": "usage_01H8X3Y4ZB",
      "user_id": "user_abc123",
      "agent_id": "agent_01H8X3Y4Z5",
      "conversation_id": "conv_xyz789",
      "credits_consumed": 3,
      "model": "Smart",
      "query_summary": "Aged receivables query",
      "timestamp": "2026-04-12T10:20:00Z"
    }
  ]
}

Allocate Credits to User

Set or update the credit allocation for a specific user.

PUT /v1/credits/users/{user_id}/allocation

Required scope: credits:write

Request Body

Field	Type	Required	Description
`monthly_limit`	integer	Yes	Maximum credits per month
`rollover_enabled`	boolean	No	Allow unused credits to roll over (default: `false`)

Example Request

curl -X PUT "https://api.agent.net.ai/v1/credits/users/user_abc123/allocation" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "monthly_limit": 750,
    "rollover_enabled": true
  }'

Example Response

{
  "data": {
    "user_id": "user_abc123",
    "monthly_limit": 750,
    "rollover_enabled": true,
    "effective_from": "2026-05-01T00:00:00Z",
    "updated_at": "2026-04-12T10:30:00Z"
  }
}

Get Usage Summary

Retrieve a high-level usage summary for the current billing period.

GET /v1/credits/summary

Required scope: credits:read

Example Request

curl -X GET "https://api.agent.net.ai/v1/credits/summary" \
  -H "Authorization: Bearer <token>"

Example Response

{
  "data": {
    "billing_period": {
      "start": "2026-04-01T00:00:00Z",
      "end": "2026-04-30T23:59:59Z"
    },
    "total_credits_used": 1580,
    "total_queries": 523,
    "active_users": 12,
    "most_used_agents": [
      {
        "agent_id": "agent_01H8X3Y4Z5",
        "name": "Financial Reporter",
        "credits_used": 450,
        "query_count": 120
      },
      {
        "agent_id": "agent_01H8X3Y4Z6",
        "name": "Inventory Tracker",
        "credits_used": 280,
        "query_count": 195
      }
    ],
    "model_distribution": {
      "Fast": { "credits": 620, "queries": 310 },
      "Smart": { "credits": 720, "queries": 180 },
      "Premium": { "credits": 240, "queries": 33 }
    }
  }
}

On this page