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

# list_behaviors

Lists the user's Behaviors, the recurring things they track (habits, routines, or recurring tasks), with schedules, reminders, category, run state, archive notes, and sub-behavior links. A parent Behavior lists its sub-behaviors (one level deep). Use it to find a Behavior id or review what the user tracks. Includes archived Behaviors unless filtered.

## Permission and annotations

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

- `title`: "List Behaviors"
- `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 |
|---|---|---|---|
| ` state ` | no | string | Which Behaviors to include. running is active and scheduling; not_running is active but ended or paused; active is both.; default: ` all `; Values: ` active `, ` archived `, ` running `, ` not_running `, ` all ` |
| ` category_id ` | no | string | Only Behaviors in this category.; format: ` uuid ` |
| ` is_opportunity ` | no | boolean | true: only Behaviors available as opportunities; false: only the others. Omit for both (contract 1.6.0). |
| ` parent_behavior_id ` | no | string | Only the sub-behaviors of this parent Behavior (contract 1.7.0).; format: ` uuid ` |
| ` hierarchy ` | no | string | top_level returns parents and standalone Behaviors; sub_behaviors returns only sub-behaviors (contract 1.7.0).; default: ` all `; Values: ` all `, ` top_level `, ` sub_behaviors ` |
| ` 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 |
|---|---|---|---|
| ` behaviors ` | yes | array |  |
| ` behaviors[] ` | yes | object | A Behavior: a recurring thing the user tracks (a habit, routine, or recurring task). |
| ` behaviors[].id ` | yes | string | format: ` uuid ` |
| ` behaviors[].title ` | yes | string |  |
| ` behaviors[].description ` | yes | string or null |  |
| ` behaviors[].location_text ` | yes | string or null |  |
| ` behaviors[].category ` | yes | object or null |  |
| ` behaviors[].category.id ` | yes | string | format: ` uuid ` |
| ` behaviors[].category.name ` | yes | string |  |
| ` behaviors[].state ` | yes | string | Archived Behaviors keep their history but schedule no new Occurrences.; Values: ` active `, ` archived ` |
| ` behaviors[].archived_at ` | yes | string or null | format: ` date-time `; pattern: ` [Zz]$ ` |
| ` behaviors[].auto_archived_at ` | yes | string or null | Set on Behaviors that an end date archived automatically before Cadence stopped archiving on an end. New ends never set it.; format: ` date-time `; pattern: ` [Zz]$ ` |
| ` behaviors[].run_state ` | yes | string | running schedules Occurrences; ended has passed its end and paused is inside a pause, both still active and shown under Not running; archived is archived.; Values: ` running `, ` ended `, ` paused `, ` archived ` |
| ` behaviors[].is_opportunity ` | yes | boolean | True when the Behavior is available as an opportunity: the person can add it to today when there is room, with or without a schedule (contract 1.6.0). |
| ` behaviors[].end_on ` | yes | string or null | Last local day the Behavior runs. Null when it has no end.; format: ` date ` |
| ` behaviors[].end_time ` | yes | string or null | Local time on end_on when it stops. Null means it stops at the end of that day.; pattern: ` ^([01][0-9]\|2[0-3]):[0-5][0-9]$ ` |
| ` behaviors[].pause ` | yes | object or null | The current or upcoming pause. Null when none is set or the pause is over. |
| ` behaviors[].pause.from_on ` | yes | string | First paused local day.; format: ` date ` |
| ` behaviors[].pause.from_time ` | yes | string or null | Local time on from_on when the pause starts. Null means the start of that day.; pattern: ` ^([01][0-9]\|2[0-3]):[0-5][0-9]$ ` |
| ` behaviors[].pause.back_on ` | yes | string | Local day the Behavior runs again by itself, from the start of the day.; format: ` date ` |
| ` behaviors[].end_date ` | yes | string or null | Deprecated: read end_on. The day after end_on, kept for one minor version.; format: ` date ` |
| ` behaviors[].default_duration_minutes ` | yes | integer or null | minimum: ` 1 ` |
| ` behaviors[].timezone ` | yes | string | IANA timezone name.; minLength: ` 1 `; maxLength: ` 64 `; pattern: <code>&#94;&#91;&#65;&#45;&#90;&#97;&#45;&#122;&#48;&#45;&#57;&#95;&#43;&#92;&#45;&#47;&#93;&#43;&#36;</code> |
| ` behaviors[].schedules ` | yes | array |  |
| ` behaviors[].schedules[] ` | yes | object |  |
| ` behaviors[].schedules[].id ` | yes | string | format: ` uuid ` |
| ` behaviors[].schedules[].recurrence ` | yes | one of several shapes | Structured recurrence rule. Natural-language rules and cron syntax are not accepted. |
| ` behaviors[].schedules[].recurrence.frequency ` | yes | string | Value: ` daily ` |
| ` behaviors[].schedules[].recurrence.interval ` | yes | integer | Repeat every N days. 1 means every day.; minimum: ` 1 ` |
| ` behaviors[].schedules[].recurrence.frequency ` | yes | string | Value: ` interval_days ` |
| ` behaviors[].schedules[].recurrence.interval_days ` | yes | integer | Repeat every N days counted from the start date.; minimum: ` 1 ` |
| ` behaviors[].schedules[].recurrence.frequency ` | yes | string | Value: ` weekly ` |
| ` behaviors[].schedules[].recurrence.interval ` | yes | integer | Repeat every N weeks. 1 means every week.; minimum: ` 1 ` |
| ` behaviors[].schedules[].recurrence.days_of_week ` | yes | array | minItems: ` 1 `; maxItems: ` 7 `; uniqueItems: ` true ` |
| ` behaviors[].schedules[].recurrence.days_of_week[] ` | yes | string | Values: ` monday `, ` tuesday `, ` wednesday `, ` thursday `, ` friday `, ` saturday `, ` sunday ` |
| ` behaviors[].schedules[].recurrence.frequency ` | yes | string | Value: ` monthly ` |
| ` behaviors[].schedules[].recurrence.interval ` | yes | integer | Repeat every N months.; minimum: ` 1 ` |
| ` behaviors[].schedules[].recurrence.day_of_month ` | yes | integer | Day of the month. In months without this day, the last day of the month is used.; minimum: ` 1 `; maximum: ` 31 ` |
| ` behaviors[].schedules[].recurrence_summary ` | yes | string | Plain-language recurrence, for example `Weekly on Monday and Thursday`. |
| ` behaviors[].schedules[].time_entries ` | yes | array |  |
| ` behaviors[].schedules[].time_entries[] ` | yes | object |  |
| ` behaviors[].schedules[].time_entries[].id ` | yes | string | format: ` uuid ` |
| ` behaviors[].schedules[].time_entries[].kind ` | yes | string | Values: ` exact `, ` range ` |
| ` behaviors[].schedules[].time_entries[].preset ` | yes | string or null | Values: ` morning `, ` afternoon `, ` evening `, ` night `, ` null ` |
| ` behaviors[].schedules[].time_entries[].start_time ` | yes | string | Local wall-clock time, 24-hour HH:MM.; pattern: ` ^([01][0-9]\|2[0-3]):[0-5][0-9]$ ` |
| ` behaviors[].schedules[].time_entries[].end_time ` | yes | string or null | Local wall-clock time, 24-hour HH:MM.; pattern: ` ^([01][0-9]\|2[0-3]):[0-5][0-9]$ ` |
| ` behaviors[].schedules[].time_entries[].label ` | yes | string | Display label, for example `7:30 AM` or `Morning`. |
| ` behaviors[].schedules[].time_summary ` | yes | string |  |
| ` behaviors[].schedule_summary ` | yes | string |  |
| ` behaviors[].reminders ` | yes | object |  |
| ` behaviors[].reminders.browser_enabled ` | yes | boolean |  |
| ` behaviors[].reminders.email_enabled ` | yes | boolean |  |
| ` behaviors[].reminders.offset_minutes ` | yes | integer | minimum: ` 0 ` |
| ` behaviors[].reminders.summary ` | yes | string |  |
| ` behaviors[].archive_notes ` | yes | array |  |
| ` behaviors[].archive_notes[] ` | yes | object |  |
| ` behaviors[].archive_notes[].id ` | yes | string | format: ` uuid ` |
| ` behaviors[].archive_notes[].archived_at ` | yes | string | format: ` date-time `; pattern: ` [Zz]$ ` |
| ` behaviors[].archive_notes[].note ` | yes | string or null |  |
| ` behaviors[].archive_notes[].updated_at ` | yes | string | format: ` date-time `; pattern: ` [Zz]$ ` |
| ` behaviors[].external_ref ` | yes | string or null | This client's external record id, when it set one at creation. |
| ` behaviors[].parent_behavior_id ` | yes | string or null | Parent Behavior id when this is a sub-behavior. Null for a top-level Behavior (contract 1.7.0).; format: ` uuid ` |
| ` behaviors[].sub_behavior_sort_order ` | yes | integer | Position among the parent's sub-behaviors, 0 first. 0 for a top-level Behavior.; minimum: ` 0 `; maximum: ` 9999 ` |
| ` behaviors[].inherit_parent_schedule ` | yes | boolean | True when this sub-behavior follows its parent's schedule; its schedules then mirror the parent's. Always false for a top-level Behavior. |
| ` behaviors[].sub_behaviors ` | yes | array | This Behavior's sub-behaviors in display order, archived ones included. Empty for a sub-behavior or a Behavior without any. |
| ` behaviors[].sub_behaviors[] ` | yes | object |  |
| ` behaviors[].sub_behaviors[].id ` | yes | string | format: ` uuid ` |
| ` behaviors[].sub_behaviors[].title ` | yes | string |  |
| ` behaviors[].sub_behaviors[].sub_behavior_sort_order ` | yes | integer | Position among the parent's sub-behaviors, 0 first.; minimum: ` 0 `; maximum: ` 9999 ` |
| ` behaviors[].sub_behaviors[].inherit_parent_schedule ` | yes | boolean | True when the sub-behavior follows its parent's schedule. |
| ` behaviors[].sub_behaviors[].active ` | yes | boolean | False when the sub-behavior is archived. |
| ` behaviors[].sub_behaviors[].run_state ` | yes | string | Values: ` running `, ` ended `, ` paused `, ` archived ` |
| ` behaviors[].created_at ` | yes | string | format: ` date-time `; pattern: ` [Zz]$ ` |
| ` behaviors[].updated_at ` | yes | string | format: ` date-time `; pattern: ` [Zz]$ ` |
| ` behaviors[].revision ` | yes | string | Opaque version token of this record. Send it back as `expected_revision` to avoid overwriting a newer change.; minLength: ` 1 `; maxLength: ` 128 `; pattern: ` ^[A-Za-z0-9._:-]+$ ` |
| ` 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_behaviors",
  "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
{
  "behaviors": [
    {
      "id": "00000001-1111-4111-8111-000000000001",
      "title": "Morning walk",
      "description": "Twenty minutes outside.",
      "location_text": null,
      "category": {
        "id": "00000003-1111-4111-8111-000000000003",
        "name": "Fitness"
      },
      "state": "active",
      "archived_at": null,
      "auto_archived_at": null,
      "run_state": "running",
      "is_opportunity": false,
      "end_on": null,
      "end_time": null,
      "pause": null,
      "end_date": null,
      "default_duration_minutes": 20,
      "timezone": "America/New_York",
      "schedules": [
        {
          "id": "00000006-1111-4111-8111-000000000006",
          "recurrence": {
            "frequency": "weekly",
            "interval": 1,
            "days_of_week": [
              "monday",
              "thursday"
            ]
          },
          "recurrence_summary": "Weekly on Monday and Thursday",
          "time_entries": [
            {
              "id": "00000007-1111-4111-8111-000000000007",
              "kind": "exact",
              "preset": null,
              "start_time": "07:30",
              "end_time": null,
              "label": "7:30 AM"
            },
            {
              "id": "00000008-1111-4111-8111-000000000008",
              "kind": "range",
              "preset": "evening",
              "start_time": "18:00",
              "end_time": "00:00",
              "label": "Evening"
            }
          ],
          "time_summary": "7:30 AM, Evening"
        }
      ],
      "schedule_summary": "Weekly on Monday and Thursday at 7:30 AM and Evening",
      "reminders": {
        "browser_enabled": true,
        "email_enabled": false,
        "offset_minutes": 0,
        "summary": "Browser reminder at the scheduled time"
      },
      "archive_notes": [],
      "external_ref": null,
      "parent_behavior_id": null,
      "sub_behavior_sort_order": 0,
      "inherit_parent_schedule": false,
      "sub_behaviors": [],
      "created_at": "2026-09-01T12:00:00Z",
      "updated_at": "2026-10-18T13:00:00Z",
      "revision": "b1.2026-10-18T13:00:00Z"
    },
    {
      "id": "00000002-1111-4111-8111-000000000002",
      "title": "Vitamin D",
      "description": "Twenty minutes outside.",
      "location_text": null,
      "category": null,
      "state": "archived",
      "archived_at": "2026-10-01T14:00:00Z",
      "auto_archived_at": null,
      "run_state": "archived",
      "is_opportunity": false,
      "end_on": null,
      "end_time": null,
      "pause": null,
      "end_date": null,
      "default_duration_minutes": 20,
      "timezone": "America/New_York",
      "schedules": [
        {
          "id": "00000006-1111-4111-8111-000000000006",
          "recurrence": {
            "frequency": "daily",
            "interval": 1
          },
          "recurrence_summary": "Daily",
          "time_entries": [
            {
              "id": "00000007-1111-4111-8111-000000000007",
              "kind": "exact",
              "preset": null,
              "start_time": "09:00",
              "end_time": null,
              "label": "9:00 AM"
            }
          ],
          "time_summary": "9:00 AM"
        }
      ],
      "schedule_summary": "Weekly on Monday and Thursday at 7:30 AM and Evening",
      "reminders": {
        "browser_enabled": true,
        "email_enabled": false,
        "offset_minutes": 0,
        "summary": "Browser reminder at the scheduled time"
      },
      "archive_notes": [
        {
          "id": "00000009-1111-4111-8111-000000000009",
          "archived_at": "2026-10-01T14:00:00Z",
          "note": "Doctor said to stop.",
          "updated_at": "2026-10-01T14:00:00Z"
        }
      ],
      "external_ref": "facets:rec_42",
      "parent_behavior_id": null,
      "sub_behavior_sort_order": 0,
      "inherit_parent_schedule": false,
      "sub_behaviors": [],
      "created_at": "2026-09-01T12:00:00Z",
      "updated_at": "2026-10-18T13:00:00Z",
      "revision": "b1.2026-10-18T13: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).
