`get_goal`

Reads one goal: its wording, versions, audience, and search state.

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

When to use it#

Before any write, to get the current scopeVersion and contextRevisionId.
To see which groups a goal is shared with, and whether it's hidden from any.
To follow a search: matching.run shows its status and progress.
To read a fellow member's goal shared with one of your groups, using its ID from get_group_details.

Inputs#

Input	Required	Type	Description
`goalId`	yes	string	Goal UUID from `list_goals`, `get_group_details`, or an earlier result

Returns#

{ "workspace": ... }:

Field	Type	Description
`goal`	object	The goal, with the `list_goals` fields. On someone else's goal, `additionalContext` is empty and `clarificationQuestion` is null.
`isOwner`	boolean	You own this goal
`selectedGroups`	list	`{ publicId, name, hidden }` for each selected group you belong to. `hidden` is only ever true for the owner.
`availableGroups`	list	Owner only: every group the goal could be shared with
`growthGroups`	list	Owner only: your groups, each with whether the goal is shared there (`isShared`), how many more networks sharing would add (`addedNetworkCount`), and who moderates it
`matching`	object	Owner only: `run`, the current search, plus `requesterMatches` and `ownNetworkMatches`. On someone else's goal, `run` is null and both lists are empty.
`searchQueued`	boolean	Owner only: Gravity will search this goal on its own shortly. Don't start a search while it's true.
`brokerableGoals`	list	On someone else's goal: people in your own Rolodex who could help with it
`chatThreadId`	string or null	On someone else's goal: your conversation with its owner about it, if there is one

matching.run describes the search for the goal's current version. It's null if the goal changed and hasn't been searched since.

Field	Description
`runId`	Search ID
`status`	`running`, `complete`, `failed`, or, rarely, `cancelled`
`stage`	`planning`, `searching`, or null
`searchProgress`	While running: `estimatedPercent` (at most 99), `completedNetworks`, and `totalNetworks`. Otherwise null.
`coverage`	`searchedMemberCount` and `groupMemberCount`
`eligibleMembers`	Members whose networks are new or updated since the last search. A `new-members` search covers them.
`failedMembers`	Members whose networks couldn't be searched last time. A `failed-networks` search retries them.
`fitPeopleCount`	How many people the search found
`error`	"The introduction search could not be completed." when the search failed, otherwise null
`startedAt`, `completedAt`, `updatedAt`	ISO 8601 timestamps
`goalScopeVersion`, `goalContextRevisionId`	The goal version this search covered

matching.requesterMatches and matching.ownNetworkMatches include email addresses for connectors and for your own contacts. To show matches, use get_goal_matches, which returns a narrower view.

workspace is null when the goal doesn't exist, you can't read it, or the ID is malformed. You can read your own ended goal by its ID. Someone else's ended goal is readable only if you already have a conversation about it.

Example#

json

{ "goalId": "6f1c2a3e-4b5d-4e6f-8a7b-9c0d1e2f3a4b" }

Trimmed result: