Get monthly usage and cost

GET 
/api/v2/Usage/monthly

Returns a paginated, month-by-month breakdown of the tenant's usage and cost. Each record aggregates one combination of subtenant, model, agent version, user, usage type, channel and connection, with token counts and the cost expressed in the tenant's currency.

Every filter is optional and they combine with AND. When neither From nor To is given, the last 12 months are returned; an explicit period may not be inverted and may not span more than 12 months.

Requires an administrator role. The caller must hold one of BackofficeTenantAdministrator, BackofficeCostAdministrator or BackofficeAgentUsageAdministrator. A plain agent API key is not enough and will receive a 403.

Request

Query Parameters

AgentCode string

Code of the agent whose usage is requested.

AgentVersion int32

Version of the agent whose usage is requested. Requires AgentCode.

UserIdentifier string

Possible values: <= 256 characters

Identifier of the end user whose usage is requested. Compared case-insensitively.

Type DailyUsageTypeEnum

Possible values: [Agent, AgentServices, Services]

Kind of usage: agent execution, services invoked by an agent, or direct service calls.

ServiceType ServiceTypeEnum

Possible values: [AudioTranscription, Embeddings, Image, Vision, SpeechGeneration, Ocr, Inference]

AI service that produced the usage, for service consumption.

Channel string

Possible values: <= 64 characters

Channel the execution came through.

From date-time

First month of the period, normalised to the first day of the month. Defaults to 12 months back when omitted. The period may not span more than 12 months.

To date-time

Last month of the period, normalised to the first day of the month. Defaults to the current month when omitted.

AIModelId uuid

The unique identifier of the AI model to use. Used instead of Vendor and ModelCode.

ModelCode string

The model code to use. Used together with Vendor when AIModelId is not provided.

Vendor string

The vendor of the model to use. Used together with ModelCode when AIModelId is not provided.

page int32

Default value: 1

The page number to retrieve.

pageSize int32

Default value: 20

Number of items per page. May not exceed 1000.

culture string

Use this param to override the culture of the response. Options: - en (default) - es

Responses

200

Returns a paginated list of monthly usage records, empty when no usage matches the filters.

application/json

Schema

Schema

items

object[]

nullable

Array [

links

object[]

nullable

Array [

method stringnullable

url stringnullable

rel stringnullable

]

month date-time

First day of the month, in UTC.

subtenantCode stringnullable

Null when the usage does not belong to a subtenant.

model

object

id uuid

code stringnullable

vendor stringnullable

name stringnullable

agent

object

id uuid

code stringnullable

name stringnullable

version int32nullable

connection

object

id uuid

name stringnullable

userIdentifier stringnullable

type DailyUsageTypeEnum (string)

Possible values: [Agent, AgentServices, Services]

The source of the usage: a direct agent execution, an AI service invoked by an agent, or a direct AI service call.

serviceType ServiceTypeEnum (string)

Possible values: [AudioTranscription, Embeddings, Image, Vision, SpeechGeneration, Ocr, Inference]

The AI service that produced the usage.

channel stringnullable

instancesCount int32

tokenInputCount int32

tokenOutputCount int32

bonifiedTokenInputCount int32

Bonified input tokens. Already included in tokenInputCount.

bonifiedTokenOutputCount int32

Bonified output tokens. Already included in tokenOutputCount.

cost

object

Costs, always expressed in the tenant's currency.

amount double

bonifiedAmount double

currency

object

isoCode stringnullable

symbol stringnullable

]

total int64
pageSize int32
page int32

links

object[]

nullable

Array [

method stringnullable

url stringnullable

rel stringnullable

]

Example (from schema)

{
  "items": [
    {
      "links": [
        {
          "method": "string",
          "url": "string",
          "rel": "string"
        }
      ],
      "month": "2024-07-29T15:51:28.071Z",
      "subtenantCode": "string",
      "model": {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "code": "string",
        "vendor": "string",
        "name": "string"
      },
      "agent": {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "code": "string",
        "name": "string",
        "version": 0
      },
      "connection": {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "name": "string"
      },
      "userIdentifier": "string",
      "type": "Agent",
      "serviceType": "AudioTranscription",
      "channel": "string",
      "instancesCount": 0,
      "tokenInputCount": 0,
      "tokenOutputCount": 0,
      "bonifiedTokenInputCount": 0,
      "bonifiedTokenOutputCount": 0,
      "cost": {
        "amount": 0,
        "bonifiedAmount": 0,
        "currency": {
          "isoCode": "string",
          "symbol": "string"
        }
      }
    }
  ],
  "total": 0,
  "pageSize": 0,
  "page": 0,
  "links": [
    {
      "method": "string",
      "url": "string",
      "rel": "string"
    }
  ]
}

400

If the page size exceeds 1000, the model is given both by id and by code and vendor, the vendor is unknown, the agent version comes without an agent code, or the period is inverted or longer than 12 months.

application/json

Schema

Schema

message stringnullable

errors

object

nullable

property name* string

Example (from schema)

{
  "message": "string",
  "errors": {}
}

401

The user is unauthorized or the session expired

403

The caller does not hold any of the roles allowed to read usage

404

The entity was not found

500

There was an unexpected error

Loading...