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

# get_account_context

Returns the account's timezone, today's local date and time, the permissions this connection has, and how fresh the data is. Use it first to learn what "today" means for this user and which Cadence tools the connection may call.

## Permission and annotations

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

- `title`: "Get Cadence account context"
- `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

No fields. Send an empty object.

## 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 |
|---|---|---|---|
| ` account_ref ` | yes | string | Stable account id for this client only. Other clients see a different value.; minLength: ` 16 `; maxLength: ` 128 `; pattern: ` ^[A-Za-z0-9_-]+$ ` |
| ` 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> |
| ` today_local_date ` | yes | string | Today's date in the account timezone.; format: ` date ` |
| ` local_time ` | yes | string | Current local time in the account timezone.; pattern: ` ^([01][0-9]\|2[0-3]):[0-5][0-9]$ ` |
| ` now ` | yes | string | Current instant.; format: ` date-time `; pattern: ` [Zz]$ ` |
| ` granted_scopes ` | yes | array | minItems: ` 1 `; uniqueItems: ` true ` |
| ` granted_scopes[] ` | yes | string | Values: ` cadence.read `, ` cadence.occurrences.write `, ` cadence.behaviors.write ` |
| ` contract_version ` | yes | string | Value: ` 1.7.0 ` |
| ` freshness ` | yes | object |  |
| ` freshness.as_of ` | yes | string | When Cadence read this data.; format: ` date-time `; pattern: ` [Zz]$ ` |
| ` freshness.occurrences_generated_through ` | yes | string or null | Last local date for which Occurrences exist. Later dates have none yet.; format: ` date ` |

## 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": "get_account_context",
  "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
{
  "account_ref": "pw_9f8e7d6c5b4a3f2e1d0c",
  "timezone": "America/New_York",
  "today_local_date": "2026-10-18",
  "local_time": "11:56",
  "now": "2026-10-18T15:56:42Z",
  "granted_scopes": [
    "cadence.read"
  ],
  "contract_version": "1.7.0",
  "freshness": {
    "as_of": "2026-10-18T15:56:42Z",
    "occurrences_generated_through": "2026-11-17"
  }
}
```

## 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).
