`start_goal_matching`

Starts a background search for one of your goals.

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

When to use it#

Only when you're asked to search. Before starting:

Read the goal with get_goal and pass its versions.
Don't start one while matching.run.status is running or searchQueued is true.
Don't start one right after save_goal. Saving already starts a search when it's needed.

Inputs#

Input	Required	Type	Description
`goalId`	yes	string	UUID of a goal you own
`goalScopeVersion`	yes	integer	`goal.scopeVersion` from your latest `get_goal`
`goalContextRevisionId`	yes	string	`goal.contextRevisionId` from your latest `get_goal`
`mode`	no	string	`full` (the default), `new-members`, or `failed-networks`
`requestId`	yes	string	A new UUID for this action. Reuse it only to retry this exact call.

Modes#

Mode	Searches	Existing matches
`full`	Every searchable network the goal's audience covers, including yours	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. With none, it completes at once with nothing new.	Matches nobody has acted on from those networks are replaced
`failed-networks`	Only networks left unfinished by a failed search	Kept

If the goal's latest search failed, any mode retries the unfinished networks. If a search is already running for this version, you get that search's ID and nothing new starts.

Returns#

{ "status", "message", "matchingRunId" }. Success means the search started, not that it finished.

Message	Status	Meaning
"The search is available in your goal."	`success`	The search started, or was already running. Follow it as described below.
"The search is available in your goal."	`error`	This `requestId` belongs to a search that failed. Read the goal to see what failed.
"This goal changed or is unavailable. Read it again before searching."	`error`	Nothing started. The goal changed since you read it, it ended or isn't yours, it has an open clarification question, or `failed-networks` found nothing to retry.
"The search could not be started. Retry it in your goal."	`error`	The search couldn't start, or this `requestId` belongs to a different goal. Read the goal before retrying.
"A current goal is required."	`error`	The arguments didn't validate.

Following the search#

Check every 30 to 60 seconds with get_goal (matching.run) or get_goal_matches (search):

running: still going. searchProgress shows how far along it is.
complete: read the matches. If failedMembers isn't empty, offer a failed-networks retry.
failed: say the search couldn't be completed, and offer a failed-networks retry.
No search (null): the goal changed since you started. Read it again.

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

Example#

json

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

Result: