Browse docslist_goal_matches
list_goal_matches
Reads a page of saved published match summaries for one of your goals.
Annotations: readOnlyHint: true · destructiveHint: false · idempotentHint: true · openWorldHint: false
Inputs#
| Input | Required | Description |
|---|---|---|
goalId | yes | Exact owned goal UUID from a goal read |
pageSize | no | Nonnegative integer; omitted or 0 means 20, capped at 100 |
pageToken | no | Returned continuation token; omitted or empty starts the list |
Keep the goal unchanged on continuation. Tokens are private, actor-bound, and expire after one hour. Restart if a token expires. These are live reads, not a snapshot across pages.
Returns#
{ "matches", "nextPageToken" }. Only an empty nextPageToken means completion, including when a page has no named matches. Follow every page before claiming complete coverage; otherwise report what you actually read. Missing and unowned goals return unavailable. A readable goal without current matches, including an ended goal, returns an empty collection.
| Match field | Description |
|---|---|
id, name | Exact match ID and readable identity; unnamed external identities are omitted |
route | { kind: "own_contact", personId } for your contact, or { kind: "through_member", connector: { memberId, name } } |
context | current or earlier; earlier does not mean assessed against edited wording |
fit | goal_fit, potential_win_win, explicit_win_win, or null for an unassessed suggestion |
introduction | not_requested, requested, or offered in the owner's current collection; connector summaries can also have sent or declined |
ownOutreach | null, chosen, connected, or not_connected; the member's own choice/report, never inferred contact consent |
Own contacts come first, then member suggestions and fit priority within each route kind, with match ID breaking ties. Separate connector paths retain separate IDs even when they name the same person.
Summaries contain no explanations, profile, or search status. Read get_goal_match using id before explaining why someone fits. Read get_goal_search for saved search status. Reading starts nothing and contacts nobody.
Example#
{
"goalId": "00000000-0000-4000-a000-000000000001",
"pageSize": 20
}
Result (synthetic data):
{
"matches": [{
"id": "00000000-0000-4000-a000-000000000002",
"name": "Synthetic candidate",
"route": { "kind": "through_member", "connector": { "memberId": "00000000-0000-4000-a000-000000000003", "name": "Synthetic connector" } },
"context": "current",
"fit": "potential_win_win",
"introduction": "not_requested",
"ownOutreach": null
}],
"nextPageToken": ""
}