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

# Usage and workspaces

> MCP tools to check API credits and to list and switch the connection's workspace

These tools are free. `get_usage` needs the **See API credit usage** permission (`usage:read`). `list_workspaces` and `switch_workspace` need no permission, and the assistant sees them only if you're in more than one workspace.

## Try these prompts

Claude and GPT picked the tools shown for these prompts in Alura's evaluation runs.

| Ask your assistant | Tools it uses |
| - | - |
| How many Alura API credits do I have left this month? | `get_usage` |
| Which Alura workspace are you working in right now, and which other workspaces can I use? | `list_workspaces` |
| Show me the saved lists in my \[Wholesale] workspace. | `list_workspaces`, `switch_workspace`, then `list_saved` |
| Save Etsy listing \[ID] to the 'Holiday 2026' list in my other workspace, \[Wholesale]. | `list_workspaces`, `switch_workspace`, `list_saved`, then `add_to_saved_list` |

## Good to know

* **A switch sticks.** It changes the connection's current workspace for every chat that uses it, until the next switch. Ask the assistant to switch back when you're done. Because later saves land in another workspace, `switch_workspace` is marked destructive, and assistants such as Claude ask before switching.
* **The workspace pays.** Calls after a switch use the new workspace's API credits and plan.
* **Owners are told.** The first time a connection switches into a workspace, that workspace's owners get an email.
* **API keys can't switch.** A key belongs to one workspace; `switch_workspace` with a key answers `workspace_locked`.

## Tools

### `get_usage`

**Get API usage.** Show the workspace's API credit usage: plan, this month's allowance, used and remaining credits, the daily ceiling, the request rate, today's fetch caps, credits spent by operation and by client, and the price of every operation. The plan itself is managed in Alura's settings. Use it when the user asks about credits, limits, spending or plans, or before a large batch of paid calls.

* **Cost of `get_usage`:** Free (0 API credits).
* **Behavior:** Read-only: changes nothing. Works on Alura's own data only.
* **Scope:** `usage:read` (see API credit usage).
* **REST:** [`GET /v1/usage`](/api-reference/account/usage/get).

| Argument | Type | Required | Description |
| - | - | - | - |
| `detail` | `concise`, `detailed` | No | `detailed` (default): every field this tool shows. `concise`: the key fields only, for long lists or a quick check. |

### `list_workspaces`

**List workspaces.** List the Alura workspaces this connection can act for, with the current one marked (`current`). Every other tool acts for the current workspace and spends its API credits. Use it before switch\_workspace, or when the user asks which workspace you are working in.

* **Cost of `list_workspaces`:** Free (0 API credits).
* **Behavior:** Read-only: changes nothing. Works on Alura's own data only.
* **Scope:** none: any connection can call it.
* **REST:** [`GET /v1/me/workspaces`](/api-reference/account/workspaces/list).

| Argument | Type | Required | Description |
| - | - | - | - |
| `cursor` | string | No | next\_cursor from the previous page. |
| `detail` | `concise`, `detailed` | No | `detailed` (default): every field this tool shows. `concise`: the key fields only, for long lists or a quick check. |

### `switch_workspace`

**Switch workspace.** Make another of the user's workspaces the current one for this connection. From the next call on, every tool acts for that workspace: its saved research, and its API credits pay. It applies to every conversation using this connection. Take the ID from list\_workspaces. Use it when the user asks to work in, or save to, another workspace.

* **Cost of `switch_workspace`:** Free (0 API credits).
* **Behavior:** **Destructive.** It overwrites the connection's current workspace, so later reads and saves go to another workspace, and the owners' notice of a first switch cannot be taken back. Safe to repeat. Switching to the workspace that is already current changes nothing, so repeating a call has no further effect.
* **Scope:** none: any connection can call it.
* **REST:** [`POST /v1/me/workspace`](/api-reference/account/workspace/switch).

| Argument | Type | Required | Description |
| - | - | - | - |
| `workspace_id` | string | Yes | The workspace to act for from the next call on: an `id` from list\_workspaces (GET /v1/me/workspaces). |
| `detail` | `concise`, `detailed` | No | `detailed` (default): every field this tool shows. `concise`: the key fields only, for long lists or a quick check. |

**Example arguments**

```json theme={null}
{
  "workspace_id": "1001"
}
```


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