AI Assistant Logs

The AI Assistant Logs API reports how many AI tokens your team and its individual users have consumed. Use it for usage monitoring, internal billing and auditing consumption per user.

Token counts cover every AI provider the assistant uses, so a total is the combined usage rather than one vendor's.

Getting started

These endpoints need an account API token, created in your Topol account under Settings -> API Tokens:

1. Give the token a name and select its permissions. Permissions can be changed later in the Manage API Tokens section.
2. Click "Create token".
3. Copy the generated key somewhere safe, since it is shown once.

The token needs the read permission, which is also the default for a newly created token. It has to belong to a team, and usage is scoped to the team that owns it, so there is no way to read another team's figures.

WARNING

Plugin initialization API keys do not work here. Requests authenticated with a plugin token are rejected with 403 and the message Plugin API tokens are not permitted on this endpoint.

All API requests must include the following headers:

{
  "accept": "application/json",
  "Authorization": "Bearer <your-api-key>"
}

Filtering by date

Every endpoint accepts date_from and date_to in ISO format. Both have to be supplied together. Passing only one leaves the result unfiltered, and the response echoes the range back only when both are present.

Endpoints overview

Get total tokens used (by team)

Retrieve the total number of AI tokens used by your team during a selected timeframe.

• URL: https://app.topol.io/api/open-ai-logs/team
• Method: GET

Request:

Optional params:

key	value
date_from (string, nullable)	Start date in ISO format
date_to (string, nullable)	End date in ISO format

Response:

{
  "success": true,
  "data": {
    "name": "Your Team",
    "total_tokens": 100,
    "date_from": "2023-01-01T00:00:00.000000Z", // if is set
    "date_to": "2023-01-01T00:00:00.000000Z" // if is set
  }
}

Get token usage per user

Use this to audit usage per team member.

• URL: https://app.topol.io/api/open-ai-logs/team-users
• Method: GET

Request:

Params:

key	value
search (string)	Search query string (in user), * acts as a wildcard
per_page (integer)	Number of results per page (default: 25)
current_page (integer)	Which page of results to return (default: 1)
sort_by (string)	Column to sort by, for example name or user
sort_by_direction	possible values: asc, desc
date_from	Start date in ISO format
date_to	End date in ISO format

Without sort_by, results come back ordered by total tokens descending.

Response:

{
  "success": true,
  "data": {
    "data": [
      {
        "team_id": 1,
        "name": "Your Team",
        "user": "UserId1",
        "total_tokens": 100
      },
      {
        "team_id": 1,
        "name": "Your Team",
        "user": "UserId2",
        "total_tokens": 200
      }
    ],
    "total_records": 2,
    "current_page": 1,
    "per_page": 25,
    "next_page": null,
    "prev_page": null,
    "last_page": 1,
    "date_from": "2023-01-01T00:00:00.000000Z", // if set
    "date_to": "2023-11-01T00:00:00.000000Z" // if set
  }
}

Get token usage for a specific user

Use this to get total usage for a specific user.

• URL: https://app.topol.io/api/open-ai-logs/user
• Method: GET

Request:

Params:

key	value
user (string)	user (required)
date_from (string, nullable)	Start date in ISO format
date_to (string, nullable)	End date in ISO format

Response:

{
  "success": true,
  "data": {
    "name": "Your Team",
    "user": "UserId",
    "total_tokens": 100,
    "date_from": "2023-01-01T00:00:00.000000Z", // if is set
    "date_to": "2023-01-01T00:00:00.000000Z" // if is set
  }
}

Error responses

Status	Body	Cause
403	{"message": "Plugin API tokens are not permitted on this endpoint."}	A plugin initialization key was used instead of an account API token
404	{"message": "Team not found"}	The token is not attached to a team
422	Laravel validation payload	A required param is missing, such as user on the per-user endpoint