---
title: "AI Assistant Logs"
description: "Track how many AI tokens your team and individual users consume, through three read-only endpoints on the Topol API."
url: https://docs.topol.io/email-editor/guide/ai-assistant-logs.html
---

# 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:**

```json
{
  "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:**

```json
{
  "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:**

```json
{
  "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:**

```json
{
  "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 |