Find matches and search again

Read a goal and its matches, then search networks that haven't been searched yet.

This is the agent workflow. The member guide gives examples of what to ask.

The request in this guide: "Any new matches for my investor goal in Founders dinner? If Priya's network hasn't been searched, search it."

1. Find the group#

Call list_groups and find Founders dinner's publicId. If more than one group could be meant, ask which one.

{}

2. Find the goal#

Call get_group_details with that publicId. In ownGoals, find the goal about investors. If more than one could fit, ask which one.

{ "groupPublicId": "3a9f0c6e1b2d4e5f8a7b6c5d4e3f2a1b" }

3. Read the goal#

Call get_goal with the goal's id. Note goal.scopeVersion and goal.contextRevisionId for later, and check matching.run and searchQueued.

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

4. Read the saved matches#

Call get_goal_matches and summarize what Gravity found. This starts nothing and contacts nobody.

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

5. Decide whether to search#

Look at matching.run from step 3:

• If it's running, or searchQueued is true, a search is already on its way. Say so and skip to step 7.
• If Priya appears in eligibleMembers, her network hasn't been searched for this version of the goal. You were asked to search it, so continue.
• Otherwise, there's nothing new to search. Say so and stop.

6. Start the search#

Call start_goal_matching with mode: "new-members", the versions from step 3, and a new requestId.

{
  "goalId": "6f1c2a3e-4b5d-4e6f-8a7b-9c0d1e2f3a4b",
  "goalScopeVersion": 3,
  "goalContextRevisionId": "c2d3e4f5-a6b7-4c8d-b9e0-f1a2b3c4d5e6",
  "mode": "new-members",
  "requestId": "5d4c3b2a-1f0e-4d9c-8b7a-6f5e4d3c2b1a"
}

If the call fails before you get a result, retry once with the original requestId and identical arguments. This reuses the admitted search without starting another; superseded goal inputs return a conflict and current state. Read current state afterward; follow Errors and limits.

7. Follow it to the end#

Call get_goal every 30 to 60 seconds until matching.run.status is complete or failed. Then read get_goal_matches again and report what's new.

For version_conflict, go back to step 3. For unavailable, resolve from current authorized goals instead of guessing another ID.

If the search remains running without progress for about 15 minutes, stop polling and tell the member they can follow it on the goal in Gravity. Don't claim it completed. For complete with unfinished networks, or failed, explain the outcome and offer a separately authorized retry. See start_goal_matching for search modes, status fields, partial completion, and stopped-search outcomes.