---
title: "Search activity"
method: POST
path: "/v1/tools/betteroff_search_activity"
tags: ["tools"]
---

# Search activity

`POST /v1/tools/betteroff_search_activity`

## Request

- Base URL: `https://api.betteroff.finance`
- URL: `https://api.betteroff.finance/v1/tools/betteroff_search_activity`
- Auth: one of:
  - OpenID Connect (`https://app.betteroff.finance/api/auth/.well-known/openid-configuration`, scopes: `activity:read`)
  - HTTP bearer

Use this when the user asks about recorded account changes or correction proposals. Read permitted record changes. For an account's correction proposals (pending or approved), set accountId (via betteroff_list_accounts), actorType=all, action=null; needs corrections:prepare. Omits security events and raw fields.

## Request body

- object
  - `accountId` string, uuid, nullable
  - `actorType` 'agent' | 'user' | 'system' | 'all', required
  - `action` 'categorize_transaction' | 'update_transaction' | 'classify_recurring' | 'confirm_debt_details' | 'apply_correction' | 'undo_correction', nullable, required
  - `limit` integer, nullable, required
  - `before` object, nullable
    - `timestamp` string, date-time, required
    - `id` string, uuid, required

## Response `200`

Tool result

- union
  - object
    - `ok` false, required
    - `requestId` string
    - `error` string, required
    - `code` string, required
    - `retryable` boolean, required
    - `nextStep` string, required
    - `field` string
    - `missingInputs` object[]
      - `id` string, required
      - `name` string, required
      - `balanceMissing` boolean, required
      - `interestRateMissing` boolean, required
      - `minimumPaymentMissing` boolean, required
  - object
    - `ok` true, required
    - `requestId` string
    - `schemaVersion` '4', required
    - `data` object, required
      - `accountId` string, uuid, nullable, required
      - `count` integer, required
      - `entries` object[], required
        - `id` string, uuid, required
        - `actorType` string, required
        - `action` string, required
        - `resourceType` string, nullable, required
        - `resourceId` string, nullable, required
        - `timestamp` string, date-time, required
        - `correction` object
          - `kind` 'category' | 'recurring' | 'debt'
          - `status` 'pending' | 'expired' | 'applied' | 'undone'
          - `appliedMode` 'selected' | 'matching', nullable
          - `reviewUrl` string, uri, required
      - `page` object, required
      - `warning` string, required
    - `currency` string, nullable, required
    - `timezone` string, required
    - `asOf` string, nullable, required
    - `revision` integer, required
    - `householdRevision` integer, required
    - `quality` object, required
      - `state` 'complete' | 'partial' | 'unavailable', required
      - `reasons` string[], required
    - `evidence` object[], required
      - `source` string, required
      - `id` string
      - `observedAt` string, nullable, required
    - `page` object, required
      - `returnedCount` integer, required
      - `totalCount` integer, nullable, required
      - `truncated` boolean, required
      - `nextCursor` Schema1, required (unresolved $ref)
    - `warnings` string[], required
    - `notes` string

## Other responses

- `400`: INVALID_INPUT (a missing, unknown, or invalid argument, named in `fields`), TOOL_CALL_REJECTED, or a body that is not JSON.
- `401`: AGENT_TOKEN_INVALID: the token is missing, expired, or revoked.
- `402`: AGENT_SUBSCRIPTION_INACTIVE or FEATURE_NOT_INCLUDED: needs BetterOff Core.
- `403`: INSUFFICIENT_SCOPE, ACCESS_DENIED, or AGENT_GRANT_REVOKED.
- `404`: TOOL_NOT_FOUND, or NOT_FOUND for a record the org does not have.
- `409`: CONFLICT: the record's state rules this call out. Read it again.
- `422`: INCOMPLETE_DATA or RESULT_TOO_LARGE. Narrow the request; don't retry as is.
- `429`: RATE_LIMITED. Retry after Retry-After seconds.
- `503`: DATA_UNAVAILABLE, DEPENDENCY_UNAVAILABLE (including the 25-second tool deadline), or AGENT_AUTHZ_UNAVAILABLE. Retryable.
- `default`: Problem details

---

[API](https://skmtc.dev/betteroff/apis/betteroff-api.md) · [All operations](https://skmtc.dev/betteroff/apis/betteroff-api/llms.txt) · [OpenAPI document](https://skmtc.dev/betteroff/apis/betteroff-api/revisions/bc858c8d428d?raw)