Skip to content
Browse docsend_goal

end_goal

Ends one goal you own, stops its searches, and archives its introduction chats as read-only. History is retained. Ending cannot be undone.

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

When to use it#

Use only when the member explicitly asks to end a goal. Resolve its exact identity and current opaque version with list_goals or get_goal. Goals the member owns for other people are eligible. A goal owned by someone else is unavailable.

Explain the consequences before acting: searches stop, introduction chats become read-only, and the goal cannot be reopened. The member's chat request authorizes execution; do not require a Gravity UI visit or another confirmation. Clarify only an ambiguous goal or another consequential choice. For several goals, use batch_end_goals.

Inputs#

InputRequiredTypeDescription
goalIdyesstringExact owned goal UUID.
expectedVersionyesstringOpaque version copied unchanged from the goal you read.
endReasonnostringachieved only when the member says they got what they needed; no_longer_needed only when they say they no longer need it. Otherwise omit it.

Never infer a reason from a generic ending request, and do not require one to finish. Ending does not by itself mark the goal achieved or an introduction successful.

Effects and retries#

An active goal's version must match. Ending advances it once, cancels live searches, withdraws pending context proposals, and archives the goal's shared introduction chats. Their history remains readable through authorized links; private Gravity conversations remain available. Other goals are unchanged, including any separate goal a recipient received from an offer.

Ending an already-ended owned goal returns no_change, even with an older supplied version. Its saved reason, retirement time, and version remain unchanged. Ending cannot correct an earlier reason or reopen the goal. A missing or inaccessible goal returns unavailable.

Returns#

Success returns status, message, outcome (ended or no_change), goal, cancelledMatchingRunIds, and a presentation link. The goal contains its lifecycle fields: id, original text, current version and scopeVersion, retiredAt, and saved endReason (null when unstated). Read get_goal for full goal details.

Errors use the common error contract. A version conflict ends nothing. Read the current goal and reconcile the member's intent before another write. After an unconfirmed outcome, read before retrying and never claim success.

Example#

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

Example response (synthetic data):

json
{
  "status": "success",
  "message": "Goal ended.",
  "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"
  ]
}