Skip to content
Browse docsbatch_end_goals

batch_end_goals

Ends an exact set of owned goals in one atomic operation. Searches stop and introduction chats become read-only; history is retained. Ending cannot be undone.

Annotations: readOnlyHint: false · destructiveHint: true · idempotentHint: true · openWorldHint: false

When to use it#

Use when the member explicitly asks to end several goals or all their goals. For “all,” read every page of a fresh list_goals until nextPageToken is empty and pass that exact set, including private goals and owned goals for other people. If the selection is incomplete or exceeds 100 goals, end none and explain the limit; never silently split the request. Lists are live, so report the selected count and actual outcomes without claiming to include later additions. For a subset, resolve its exact identities and versions from list_goals or get_goal. An empty list needs no ending call.

Explain before acting that ending stops searches, archives introduction chats as read-only, and cannot be undone. The chat request authorizes immediate execution without a Gravity UI confirmation. Do not require a reason or infer achievement.

Inputs#

InputRequiredTypeDescription
requestsyeslist of objectsBetween 1 and 100 exact ending requests. Each goal may appear only once.

Each request has the same fields as end_goal: required goalId and expectedVersion, and optional endReason. Supply achieved only for a stated successful outcome or no_longer_needed for a stated abandoned need. Omit the reason when unstated. Reasons can differ between goals.

Atomicity and retries#

Every goal must belong to the member. Every selected active goal must still have its supplied version. The application locks the complete set and checks all preconditions before changing any goal, search, or pending proposal. A validation, ownership, or version failure ends none. A database failure rolls back the entire transaction.

Already-ended owned goals count as no_change, regardless of the supplied version, and keep their saved reason and retirement time. They do not prevent other selected active goals from ending. Repeating a successful batch changes nothing further. Results follow request order.

After a conflict, read the selected goals and reconcile the request. Never silently remove a conflicting goal and retry a smaller set. After an unconfirmed outcome, read before retrying; do not claim that nothing changed. The atomic guarantee covers stored lifecycle changes; notification or response failures after commit can leave the reported outcome unconfirmed.

A call accepts at most 100 goals. A larger request requires several batches, each atomic independently; explain that limit before proceeding. This tool accepts explicit identities, with no filter or “all” selector that could sweep in newly created goals.

Returns#

Success returns status, message, and results. Each result contains the same outcome, lifecycle goal, and cancelledMatchingRunIds as end_goal, plus its exact presentation link. message counts newly ended goals; no_change entries are not counted as newly ended. Full goal details remain available through get_goal. Errors use the common contract, with no partial-success result.

Example#

json
{
  "requests": [
    {
      "goalId": "00000000-0000-4000-a000-000000000001",
      "expectedVersion": "00000000-0000-4000-8000-000000000901"
    }
  ]
}

Example response (synthetic data):

json
{
  "status": "success",
  "message": "Ended 1 goal.",
  "results": [
    {
      "outcome": "ended",
      "goal": {
        "id": "00000000-0000-4000-a000-000000000001",
        "text": "Find design partners",
        "scopeVersion": 3,
        "retiredAt": "2026-10-20T00:00:00.000Z",
        "endReason": null,
        "version": "00000000-0000-4000-8000-000000000901"
      },
      "cancelledMatchingRunIds": [
        "00000000-0000-4000-a000-000000000002"
      ]
    }
  ]
}