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

# fetch

Returns the full text of one `search` result: a Behavior's definition, an Occurrence and its note, or a day note. Use it after `search` to read a result. A day note is the user's one note about a whole calendar date (for example "Travel day" or "Sick"). It is not an Occurrence note, has no status, and never changes Completed, Not Completed, Unresolved, Needs decision, adherence, or reminders.

## Permission and annotations

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

- `title`: "Fetch Cadence record"
- `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 |
|---|---|---|---|
| ` id ` | yes | string | Result id from `search`: `behavior:<uuid>`, `occurrence:<uuid>`, or `day_note:<uuid>`.; maxLength: ` 64 `; pattern: ` ^(behavior\|occurrence\|day_note):[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ ` |

## 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 |
|---|---|---|---|
| ` id ` | yes | string | Result id from `search`: `behavior:<uuid>`, `occurrence:<uuid>`, or `day_note:<uuid>`.; maxLength: ` 64 `; pattern: ` ^(behavior\|occurrence\|day_note):[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ ` |
| ` title ` | yes | string |  |
| ` text ` | yes | string | Plain-text rendering of the record. User-entered text is quoted as data. |
| ` url ` | yes | string | Link to the record in the Cadence web app.; format: ` uri `; maxLength: ` 2048 `; pattern: ` ^https:// ` |
| ` metadata ` | yes | object |  |
| ` metadata.kind ` | yes | string | Values: ` behavior `, ` occurrence `, ` day_note ` |
| ` metadata.behavior_id ` | no | string | Present for Behavior and Occurrence results. Absent for day notes.; format: ` uuid ` |
| ` metadata.local_date ` | no | string | Calendar date (YYYY-MM-DD) in the account timezone.; format: ` date ` |
| ` metadata.status ` | no | string | Values: ` unresolved `, ` completed `, ` not_completed ` |

## 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": "fetch",
  "arguments": {
    "id": "behavior:00000001-1111-4111-8111-000000000001"
  }
}
```

## 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
{
  "id": "occurrence:00000005-1111-4111-8111-000000000005",
  "title": "Morning walk on 2026-10-18",
  "text": "Status: Completed\nNote: \"Felt good.\"",
  "url": "https://app.cadence-me.com/timeline?date=2026-10-18&occurrence=00000005-1111-4111-8111-000000000005",
  "metadata": {
    "kind": "occurrence",
    "behavior_id": "00000001-1111-4111-8111-000000000001",
    "local_date": "2026-10-18",
    "status": "completed"
  }
}
```

## 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`.
- `not_found`: No record with that id exists for this account.

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