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: truedestructiveHint: falseidempotentHint: trueopenWorldHint: 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: ^[A-Za-z0-9_+\-/]+$ |
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.
{
"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.
{
"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_errorsnames 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 afterretry_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 sameidempotency_key.
Output size limits can also return limit_exceeded. See error handling, limits, and safe retries.