Skip to content
Browse docslist_goals

list_goals

Reads a page of authorized goal resources. By default, lists active goals you own, including private goals and goals you created for other people. Reading changes nothing and starts no search.

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

When to use it#

Start here to identify goals and read their content, authorship, audience and edit context. Ownership alone does not establish who wrote the wording. Use get_goal for one goal in the same view. Use list_group_goals to scope the same resources to active goals readable in a particular group.

For “end all my goals,” gather every page of a fresh list with the default filter before passing the exact selected IDs and opaque versions to batch_end_goals. If the selection is incomplete or contains more than 100 goals, end none and explain the limit; never silently split an atomic request. A complete empty list needs no ending call. Report the selected count and actual outcomes: this live collection does not promise a snapshot or include goals created after selection.

Inputs#

FieldRequiredTypeDescription
filternostringEmpty defaults to isOwner = true AND retiredAt = null. An explicit filter replaces that default. Supports isOwner = true/false, retiredAt = null (active), retiredAt != null (ended), =, !=, AND, OR, NOT and parentheses.
viewnostringbasic (default) or full; Full adds up to 20 authorized match assessments per goal.
pageSizenonumberNonnegative integer. Omitted or 0 means 20; values above 100 are capped.
pageTokennostringOmit or use an empty string for the first page; otherwise return nextPageToken unchanged.

Continue until nextPageToken is empty, even after an empty page. Keep the filter unchanged; only page size may change between pages. Tokens are opaque, bound to the operation, authenticated member and filter, and expire after one hour. An invalid, expired, or mismatched token returns invalid_argument; restart without it. Each page rechecks current authorization and filter conditions. An explicit isOwner = true filter includes ended owned goals. Shared ended goals require current visibility and a retained conversation.

Returns#

{ "goals": [...], "nextPageToken": "..." }, newest saved first, then goal ID. Each entry is the same base goal resource as get_goal: id, text, owner, beneficiary, authorship, version, scopeVersion, suggestedByGravity, audience, createdAt, retiredAt, isOwner, additionalContext, clarificationQuestion, and endReason.

Only owners receive private context, clarification, ending reasons and edit versions. Other viewers receive the same redacted fields and authorized audience as Get. Copy an owned goal's version unchanged as expectedVersion for an edit or ending; visibility changes invalidate it too. Full includes a bounded matches page as described in Get. Basic omits it and performs no matching reads. Search and offer state remain separate reads.

Example#

json
{ "pageSize": 20 }

Result (synthetic data):

json
{
  "goals": [
    {
      "id": "00000000-0000-4000-a000-000000000001",
      "text": "Find design partners",
      "beneficiary": null,
      "authorship": null,
      "owner": {
        "memberId": "00000000-0000-4000-a000-000000000003",
        "name": "Synthetic member"
      },
      "additionalContext": "Synthetic private details",
      "clarificationQuestion": null,
      "scopeVersion": 2,
      "version": "00000000-0000-4000-8000-000000000901",
      "suggestedByGravity": false,
      "retiredAt": null,
      "endReason": null,
      "createdAt": "2026-10-09T00:00:00.000Z",
      "isOwner": true,
      "audience": [
        {
          "groupPublicId": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
          "name": "Synthetic founders",
          "visibility": "hidden"
        }
      ]
    }
  ],
  "nextPageToken": ""
}