> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tess.im/llms.txt
> Use this file to discover all available pages before exploring further.

# Workspace usage

> List agent execution history for a workspace with filters, pagination, and enriched fields.

Your API token must be allowed to **use agents** (`use_agents`), and you must have access to the workspace—the same layers as other agent and file API routes (Sanctum authentication, workspace access check).

### **Code Examples**

```http cURL theme={null}
curl --request GET \
  --url 'https://api.tess.im/workspaces/usage?range=7d&page=1&per_page=20' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'x-workspace-id: YOUR_WORKSPACE_ID' \
  --header 'Accept: application/json' \
  --header 'x-workspace-id: YOUR_WORKSPACE_ID'
```

```json Node.js theme={null}
const axios = require('axios');

const config = {
  method: 'get',
  url: 'https://api.tess.im/workspaces/usage',
  params: {
    range: '7d',
    page: 1,
    per_page: 20
  },
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
      'x-workspace-id': 'YOUR_WORKSPACE_ID',
    'Accept': 'application/json',
    'x-workspace-id': 'YOUR_WORKSPACE_ID'
  }
};

try {
  const response = await axios(config);
  console.log(response.data);
} catch (error) {
  console.error(error);
}
```

```python Python theme={null}
import requests

url = "https://api.tess.im/workspaces/usage"
params = {
    "range": "7d",
    "page": 1,
    "per_page": 20
}
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
      "x-workspace-id": "YOUR_WORKSPACE_ID",
    "Accept": "application/json",
    "x-workspace-id": "YOUR_WORKSPACE_ID"
}

response = requests.get(url, params=params, headers=headers)
print(response.json())
```

```php PHP theme={null}
<?php
$curl = curl_init();
$query = http_build_query([
  'range' => '7d',
  'page' => 1,
  'per_page' => 20
]);

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.tess.im/workspaces/usage?" . $query,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer YOUR_API_KEY",
      "x-workspace-id: YOUR_WORKSPACE_ID",
    "Accept: application/json",
    "x-workspace-id: YOUR_WORKSPACE_ID"
  ]
]);

$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);

if ($err) {
  echo "Error: " . $err;
} else {
  echo $response;
}
```

```java Java theme={null}
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.tess.im/workspaces/usage?range=7d&page=1&per_page=20"))
    .header("Authorization", "Bearer YOUR_API_KEY")
      .header("x-workspace-id", "YOUR_WORKSPACE_ID")
    .header("Accept", "application/json")
    .header("x-workspace-id", "YOUR_WORKSPACE_ID")
    .GET()
    .build();

HttpResponse<String> response = client.send(request,
    HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
```

```go Go theme={null}
package main

import (
    "fmt"
    "io/ioutil"
    "net/http"
)

func main() {
    client := &http.Client{}
    req, err := http.NewRequest("GET", "https://api.tess.im/workspaces/usage?range=7d&page=1&per_page=20", nil)
    if err != nil {
        fmt.Println(err)
        return
    }

    req.Header.Add("Authorization", "Bearer YOUR_API_KEY")
    req.Header.Add("x-workspace-id", "YOUR_WORKSPACE_ID")
    req.Header.Add("Accept", "application/json")
    req.Header.Add("x-workspace-id", "YOUR_WORKSPACE_ID")

    resp, err := client.Do(req)
    if err != nil {
        fmt.Println(err)
        return
    }
    defer resp.Body.Close()

    body, err := ioutil.ReadAll(resp.Body)
    if err != nil {
        fmt.Println(err)
        return
    }

    fmt.Println(string(body))
}
```

```jsonnet .NET theme={null}
using System;
using System.Net.Http;
using System.Threading.Tasks;

class Program
{
    static async Task Main(string[] args)
    {
        using (var client = new HttpClient())
        {
            client.DefaultRequestHeaders.Add("Authorization", "Bearer YOUR_API_KEY");
            client.DefaultRequestHeaders.Add("x-workspace-id", "YOUR_WORKSPACE_ID");
            client.DefaultRequestHeaders.Add("Accept", "application/json");
            client.DefaultRequestHeaders.Add("x-workspace-id", "YOUR_WORKSPACE_ID");

            try
            {
                var response = await client.GetAsync("https://api.tess.im/workspaces/usage?range=7d&page=1&per_page=20");
                response.EnsureSuccessStatusCode();
                string responseBody = await response.Content.ReadAsStringAsync();
                Console.WriteLine(responseBody);
            }
            catch (HttpRequestException e)
            {
                Console.WriteLine("Exception: " + e.Message);
            }
        }
    }
}
```

```ruby Ruby theme={null}
require 'uri'
require 'net/http'

uri = URI('https://api.tess.im/workspaces/usage?range=7d&page=1&per_page=20')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Get.new(uri)
request['Authorization'] = 'Bearer YOUR_API_KEY'
request['x-workspace-id'] = 'YOUR_WORKSPACE_ID'
request['Accept'] = 'application/json'
request['x-workspace-id'] = 'YOUR_WORKSPACE_ID'

response = http.request(request)
puts response.read_body
```

### **Headers**

**x-workspace-id** `integer` *required*

Workspace ID. **Required as of 2026-09-01.** Until then, if omitted, the user's selected workspace is used (deprecated). After the cutoff, a missing header returns **422**.

### **Query parameters**

**range** `string`

Relative window: 1d, 7d, or 30d. Ignored if both start\_date and end\_date are sent. If no date parameters are sent, the effective default is 30d.

**start\_date** `date (YYYY-MM-DD)`

Start of a custom range (inclusive). Required with end\_date.

**end\_date** `date (YYYY-MM-DD)`

End of a custom range (inclusive). Must be greater than or equal to start\_date. Required with start\_date. The span cannot exceed 90 days; otherwise 422.

**user\_id** `integer`

Filter by the user who ran the agent. Without workspace permission to read other users' activity, you only see your own executions; filtering by another user's id returns 403.

**type** `string`

Agent type filter: all, chat, image, text, voiceover, video, code. all or omitted means no type filter.

**page** `integer`

Page number. Default 1, minimum 1.

**per\_page** `integer`

Page size. Default 20, between 1 and 100.

**Date windows**

* With **`start_date` + `end_date`**: the inclusive range is capped at **90 days**.
* With **`range`**: the window is relative to the **end of the current day** (`1d` last 24 hours from that instant; `7d` / `30d` last seven or thirty calendar days from that end).
* If the **`usage_history_min_date`** feature is enabled in app settings, the effective start of the range is not earlier than that date (silent clamp).

**Caching**

* Listings are cached about **60 seconds** per workspace, filters, and page. Identical requests within that window may return the same payload.

### **Response**

```json theme={null}
{
  "items": [
    {
      "id": "183450",
      "created_at": "2026-04-07 16:17:09",
      "user_id": 16643,
      "type": "chat",
      "status": "succeeded",
      "email": "user@example.com",
      "credits": 1.5,
      "name": "My personal assistant",
      "slug": "9b4994e3-07e9-4163-b5c0-9c4f18945eda-my-personal-assistant",
      "output": "This content is only available on Tess",
      "root_id": null,
      "execution_origin": "Platform",
      "source": "current",
      "used_model": "gpt-4o-mini",
      "execution_mode": "chat",
      "tokens": {
        "input": 1240,
        "output": 320,
        "total": 1560
      },
      "link": "/dashboard/user/ai/chat/ai-chat/9b4994e3-07e9-4163-b5c0-9c4f18945eda-my-personal-assistant?_chat_id=183450"
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 20,
    "has_more": false
  }
}
```

Pagination uses **`has_more`**: the service requests `per_page + 1` rows; if the extra row exists, **`has_more`** is `true` and only the first **`per_page`** items appear in **`items`**.

### **Item fields**

| **Field** | **Description** |
| :- | :- |
| id | Execution id, or a synthetic id such as `chat-edited-{user_openai_id}` for edited chats. |
| created\_at | Timestamp of the execution. |
| user\_id | User who ran the agent. |
| type | Agent type from the agent definition (for example `chat`, `image`, `text`, `voiceover`, `video`, `code`). |
| status | `succeeded` or `failed` (non-success statuses map to `failed`). |
| email | Email of the executing user. |
| credits | Credits charged; **0** when status is not `succeeded`. |
| name | Agent title. |
| slug | Agent slug. |
| output | For **current** rows: for `image`, `video`, and `voiceover` this is the real output; for other types it is the fixed text **`This content is only available on Tess`**. For **archived**: **`This item was deleted.`** For **edited**: **`This item was edited.`** |
| root\_id | Conversation root for chats, when present. |
| execution\_origin | Taken from execution metadata when available. |
| source | `current`, `archived`, or `edited`. |
| used\_model | Model name when stored (`user_openai.used_model`, execution metadata, or usage-pricing breakdown for Agent Mode runs); **`null`** for edited rows or when no model can be resolved. |
| tokens | Object `{ "input", "output", "total" }` when token billing applies. For normal chat, values come from `detailed_credits` when `metric == "token"`. For **Agent Mode** runs, values come from execution metadata even when `detailed_credits` is zeroed. **`null`** for image, video, and voiceover (billed per execution, not per token). |
| execution\_mode | **`agent`** for Agent Mode runs, **`chat`** for normal chat conversations, or **`null`** for non-chat execution types. Helps distinguish agent orchestration from standard chat when reviewing usage. |
| link | URL or app path to open the resource when applicable; **`null`** for `archived` and `edited`, and for types without a link. **Chat (current):** path `/dashboard/user/ai/chat/ai-chat/{slug}?_chat_id={id}` using **`root_id`** when set, else row **`id`**. **Image / video / voiceover (current):** signed or public URL from storage when `output` is usable; otherwise **`null`**. |

### **Errors**

| **Status** | **When** |
| :- | :- |
| 401 | Missing or invalid authentication (Sanctum). |
| 403 | No access to the workspace, or **`user_id`** targets another user without permission to view their executions. |
| 422 | Invalid query parameters (Laravel validation), invalid or missing workspace id, invalid dates, or a custom range longer than **90 days**. |

Validation errors use the standard Laravel error payload; some workspace errors return JSON `{ "message": "..." }` with a translated message.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.