---
title: "list_categories"
description: "List categories: inputs, outputs, permissions, examples, and errors."
canonical_url: https://cadence-me.com/developers/tools/list_categories
last_updated: 2026-10-18
status: stable
source: src/data/developer-reference.json
---

# list_categories

Lists the user's Behavior categories in display order. Use it to choose a category id when creating or editing a Behavior.

## Permission and annotations

Required scope: `cadence.read`. Contract 1.7.0; available since 1.0.0.

- `title`: "List categories"
- `readOnlyHint`: true
- `destructiveHint`: false
- `idempotentHint`: true
- `openWorldHint`: false

Reads account data and changes nothing, so readOnlyHint is true. Claude runs read-only tools without per-call confirmation, and OpenAI asks for readOnlyHint on every read. openWorldHint is false because the tool reaches only the user's own Cadence account.

## Input

Required means required within the containing object. Variant fields apply only to that variant; children of nullable values apply when non-null. Unknown fields are rejected.

| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
| ` updated_since ` | no | string | Return only records changed at or after this instant. Use it for incremental reads.; format: ` date-time ` |
| ` page_size ` | no | integer | Items per page.; minimum: ` 1 `; maximum: ` 100 `; default: ` 50 ` |
| ` cursor ` | no | string | Opaque `next_cursor` from the previous page.; minLength: ` 1 `; maxLength: ` 512 `; pattern: ` ^[A-Za-z0-9_-]+$ ` |

## Output

Required means required within the containing object. Variant fields apply only to that variant; children of nullable values apply when non-null. Unknown fields are rejected.

| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
| ` categories ` | yes | array |  |
| ` categories[] ` | yes | object |  |
| ` categories[].id ` | yes | string | format: ` uuid ` |
| ` categories[].name ` | yes | string |  |
| ` categories[].description ` | yes | string or null |  |
| ` categories[].sort_order ` | yes | integer |  |
| ` categories[].created_at ` | yes | string | format: ` date-time `; pattern: ` [Zz]$ ` |
| ` categories[].updated_at ` | yes | string | format: ` date-time `; pattern: ` [Zz]$ ` |
| ` next_cursor ` | yes | string or null | Cursor for the next page, or null when this is the last page.; minLength: ` 1 `; maxLength: ` 512 `; pattern: ` ^[A-Za-z0-9_-]+$ ` |

## Example call

Synthetic contract fixture. Replace identifiers and dates with records returned for your account. This is the SDK tools/call payload, not a complete HTTP request.

```json
{
  "name": "list_categories",
  "arguments": {}
}
```

## Example result

Synthetic success data from a contract fixture, shown as structuredContent. Input and output examples validate independently; they are not a recorded transaction.

```json
{
  "categories": [
    {
      "id": "00000003-1111-4111-8111-000000000003",
      "name": "Fitness",
      "description": null,
      "sort_order": 2,
      "created_at": "2026-09-01T12:00:00Z",
      "updated_at": "2026-09-01T12:00:00Z"
    }
  ],
  "next_cursor": null
}
```

## Errors

- `invalid_input`: The input does not match the tool's schema or rules. `field_errors` names each problem.
- `authentication_required`: The access token is missing, expired, revoked, or issued for another resource. Reconnect Cadence.
- `rate_limited`: Too many requests for this connection. Retry after `retry_after_seconds`.
- `service_unavailable`: Cadence integrations are temporarily unavailable.
- `internal_error`: Cadence could not complete the request. Nothing is assumed to have changed; retry once with the same `idempotency_key`.

Output size limits can also return `limit_exceeded`. See [error handling](/developers/errors), [limits](/developers/limits), and [safe retries](/developers/idempotency).
