Matches and searches

A match is a person Gravity found who may help with your goal. Searches find them, and run in the background.

What a match is#

Each match has a path to the person:

Route	Meaning
`people_you_know`	Someone in your own Rolodex
`through_member`	Someone a fellow member knows. That member is the connector, who could introduce you.

A match explains who the person is, how they could help, and why meeting could be useful to them, with a strength for each direction. A match through a connector shows the person's name and public LinkedIn information when Gravity has it. It never shows their contact details, the connector's relationship with them, or how the connector knows them.

A match is a possibility. It doesn't mean the person or the connector has agreed to anything, and Gravity never contacts the person. To ask for an introduction, open the goal in Gravity. You ask the connector there, and the connector decides.

Saved matches and new searches#

Reading matches and starting a search are separate.

get_goal_matches reads matches Gravity already found. It starts nothing and contacts nobody.
start_goal_matching starts a new search. Use it only when you've been asked to.

Saving a goal with save_goal already starts a search when it changes what Gravity should look for, so there's no need to start one right after saving.

Search modes#

Mode	Searches	Existing matches
`full`	Every searchable network the goal's audience covers, including your own	If the goal was searched before, matches nobody has acted on are replaced. Requested, dismissed, and connector-suggested matches stay.
`new-members`	Networks not yet searched for this version of the goal, networks with new information, and networks whose last search failed	Matches nobody has acted on from those networks are replaced
`failed-networks`	Only networks left unfinished by a failed search	Kept

A goal has at most one search running. Starting another while one runs returns the running search.

Following a search#

A search runs in the background. Gravity doesn't push updates over MCP, so check on it every 30 to 60 seconds with get_goal, which includes progress, or get_goal_matches.

Status	Meaning	Next step
`running`	Still searching. `searchProgress` shows how far along it is.	Keep checking.
`complete`	Done	Read the matches. If `failedMembers` isn't empty, some networks couldn't be searched. Offer to retry them with `failed-networks`.
`failed`	The search couldn't be completed	Offer to retry with `failed-networks`.
No search (`null`)	The goal changed since its last search	Read the goal again.

If a search still shows running and its progress hasn't moved for about 15 minutes, stop checking. Let the member know it's still running and that they can follow it on the goal in Gravity.