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#
| Input | Required | Type | Description |
|---|---|---|---|
goalId | yes | string | Exact owned goal UUID. |
expectedVersion | yes | string | Opaque version copied unchanged from the goal you read. |
endReason | no | string | achieved 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#
{
"goalId": "00000000-0000-4000-a000-000000000001",
"expectedVersion": "00000000-0000-4000-8000-000000000901"
}
Example response (synthetic data):
{
"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"
]
}
Related#
- Goal editing and ending workflow
update_goaledits fields and never ends a goal.