Discovery

Pages through the workspace's Discovery runs (newest first), as the Discovery history in the app: filter by status, platform or a text match on the search. `page` starts at 1; `limit` is at most 50. Each run carries its status, requested and found counts and cache expiry. Requires discovery:read and a member with Discovery access (an admin, or a member an admin granted Discovery): anyone else gets 404.

MCP tool

list_discovery_runs

Scopes

discovery:read

Members

admin, manager, scout, viewer

Idempotency-Key

Ignored (read)

Rate weight

1

Returns one run of this workspace: status (queued → running → completed / failed / cancelled), requested and found counts, the cache expiry and the provider units it used. Poll it after run_discovery_search until it is completed, then page the results with list_discovery_results. Another workspace's run id is 404.

MCP tool

get_discovery_run

Scopes

discovery:read

Members

admin, manager, scout, viewer

Idempotency-Key

Ignored (read)

Rate weight

1

Pages through one run's results in rank order: each result has its platform, handle, profile data from the provider, scores, status (candidate / imported / existing / rejected) and creator_id once it is on the roster. Profile text (bios, names, captions) is authored by the creators, not the agency: it is labelled untrusted. `offset` + `limit` (≤ 50) page through the run. Another workspace's run id is 404.

MCP tool

list_discovery_results

Scopes

discovery:read

Members

admin, manager, scout, viewer

Idempotency-Key

Ignored (read)

Rate weight

1

Untrusted fields

data

The support diagnostics the app shows for one run: each provider call (cache hit or miss, provider units used, error), the cost decisions taken before spending, enrichment events, result counts and alerts, with a copyable summary. Free-text values are sanitised (secrets redacted, strings bounded). Another workspace's run id is 404.

MCP tool

get_discovery_run_diagnostics

Scopes

discovery:read

Members

admin, manager, scout, viewer

Idempotency-Key

Ignored (read)

Rate weight

1

Cancels a queued or running run of this workspace and aborts its active provider calls, as the app's Cancel does (400 for a run that already finished, checked atomically). A search started over the API holds its credits until the run ends: a cancelled run is charged only for the result pages it already delivered, at the quoted per-page price, and the rest is released (also back to the key's daily cap); list_discovery_results then shows exactly the charged pages. Requires discovery:spend (the scope that starts runs) and an admin or manager member. Another workspace's run id is 404.

MCP tool

cancel_discovery_run

Scopes

discovery:spend

Members

admin, manager

Idempotency-Key

optional

Rate weight

1

Imports up to 25 results of one run into the roster through the app's own import — the creator, their platform profile and metrics — and with add_to_pipeline also into the pipeline. A result already on the roster is linked, not duplicated. Each result answers its own outcome: imported (with creator_id) or failed with an error code — e.g. trial_limit_reached when a trial workspace's roster is full. Billable seats sync after an import. Free (no Discovery credits). Requires discovery:read and roster:write, an admin or manager member, and Discovery access. Another workspace's run or result is 404.

MCP tool

import_discovery_results

Scopes

discovery:read + roster:write

Members

admin, manager

Idempotency-Key

optional

Rate weight

1

Adds results of one run to a creator list of this workspace, importing each creator into the roster first when it is not there yet — the app's Discovery "Add to list". Free (no Discovery credits). Requires discovery:read, lists:write and roster:write (it can create roster creators), an admin or manager member, and Discovery access. Another workspace's run, result or list is 404; a trial workspace whose roster is full gets 402 trial_limit_reached.

MCP tool

add_discovery_results_to_list

Scopes

discovery:read + lists:write + roster:write

Members

admin, manager

Idempotency-Key

optional

Rate weight

1

Returns the stored creator report (audience demographics, metrics, contact email when the provider has one) for one Discovery result — free, never a provider call. status is available with the report, or unavailable when this workspace does not hold it: buy it with preflight_creator_report + purchase_creator_report. The preflight block says what loading it would cost. Report text (bio, names) is authored by the creator: it is labelled untrusted. Another workspace's run or result is 404.

MCP tool

get_creator_report

Scopes

discovery:read

Members

admin, manager, scout, viewer

Idempotency-Key

Ignored (read)

Rate weight

1

Untrusted fields

report

Loads the creator report you priced with preflight_creator_report, presenting its quote_token. A report this workspace holds answers at 0 credits; a fresh report another workspace bought is sold without a provider call; otherwise the provider is called. The charge is keyed by the report, so the same report is never charged twice — whatever the retries or Idempotency-Keys. Charged exactly as in the app: a provider pull that returns no report still costs its credits (the rate card). On a key left on "Ask for approval in TLNT" a paid report is queued for an admin (202 pending_approval); a 0-credit (cached) report always answers directly. Report text (bio, names) is authored by the creator: labelled untrusted. Requires discovery:spend, an Idempotency-Key, an admin or manager member with Discovery access.

MCP tool

purchase_creator_report

Scopes

discovery:spend

Members

admin, manager

Approval

Runs directly; queued when the credential asks for approval for discovery_spend

Idempotency-Key

required

Rate weight

5

Untrusted fields

report

The workspace's customer-credit balance for the current period (the figure the app's credits chip shows): credits granted (per billable manager on per-seat plans), spent, released by failed actions, remaining and the date it resets. remaining is null and metered false on a plan with no credit pool (nothing is ever charged). Credits are integers; one credit is the unit every Discovery price is quoted in. Requires discovery:read.

MCP tool

get_discovery_credits

Scopes

discovery:read

Members

admin, manager, scout, viewer

Idempotency-Key

Ignored (read)

Rate weight

1

The customer-credit ledger for the current period, newest first (the app's credit history): each spend (negative amount) with what it was for, each release (a failed or cancelled action handing credits back) and grant, who drew it and the balance after it. `limit` is at most 200. Requires discovery:read.

MCP tool

list_discovery_credit_history

Scopes

discovery:read

Members

admin, manager, scout, viewer

Idempotency-Key

Ignored (read)

Rate weight

1

Lists the workspace's saved Discovery searches (presets) the key's member can see: every shared one, plus their own private ones — another member's private saved search never leaves the database. Each carries its search, schedule (off / daily / weekly) and whether this member can edit it. `q` matches the name; `limit` ≤ 50. A seeded budget cap is hidden from a member who cannot see money. Requires discovery:read.

MCP tool

list_discovery_presets

Scopes

discovery:read

Members

admin, manager, scout, viewer

Idempotency-Key

Ignored (read)

Rate weight

1

Returns one saved search the key's member can see (shared, or their own). Another member's private saved search and another workspace's id are both 404. Requires discovery:read.

MCP tool

get_discovery_preset

Scopes

discovery:read

Members

admin, manager, scout, viewer

Idempotency-Key

Ignored (read)

Rate weight

1

Sets a saved search's schedule to off: no more scheduled runs, so no more recurring spend. Turning a schedule ON is recurring spend and follows the credential's Discovery credits setting (schedule_discovery_preset); turning it off never needs approval. Requires discovery:spend, an admin or manager member (or the saved search's owner). Another workspace's id, or another member's private saved search, is 404.

MCP tool

unschedule_discovery_preset

Scopes

discovery:spend

Members

admin, manager

Idempotency-Key

optional

Rate weight

1

Free. Prices one Discovery search exactly as the workbench does — per 15-result page (classic filters 3 credits a page, AI text 6 and lookalike 6), cache applied — and checks the workspace can run it (plan allowance, credit balance, provider guards). When it can, returns a signed quote_token (valid 5 minutes, usable only by this key and its member, for exactly this search_plan) for run_discovery_search: pass the same search_plan and lookalike_source. A fully cached search is quoted 0 credits. When it cannot run, quote is null and reason_codes say why (e.g. customer_credit_balance_exceeded). Requires discovery:spend, an admin or manager member with Discovery access.

MCP tool

preflight_discovery_search

Scopes

discovery:spend

Members

admin, manager

Idempotency-Key

Ignored (read)

Rate weight

1

Starts one Discovery search (a run) for the search_plan and lookalike_source you priced with preflight_discovery_search, presenting its quote_token. Credits: at most the quoted amount; the run holds them until it finishes — a run that fails releases them, and a cancelled run is charged only for the result pages it delivered (the rest released at the quoted per-page price). Returns 201 { status: "started", data.run } (poll get_discovery_run, then list_discovery_results). Retrying with the same quote never starts or charges a second run (status replayed). By default it runs within the credential's daily Discovery-credit cap (100 by default; 429 daily_credit_cap_reached). When the credential asks for approval in TLNT for Discovery credits, a priced search is queued for an admin to approve in TLNT instead (202 pending_approval). 409 quote_expired / quote_invalid / quote_stale mean: preflight again. 402 insufficient_credits when the balance cannot cover it. Requires discovery:spend, an Idempotency-Key, an admin or manager member with Discovery access.

MCP tool

run_discovery_search

Scopes

discovery:spend

Members

admin, manager

Approval

Runs directly; queued when the credential asks for approval for discovery_spend

Idempotency-Key

required

Rate weight

5

Free. Prices the full creator report (audience demographics, metrics, contact email when the provider has one) for one Discovery result: 0 credits when this workspace already holds a fresh copy, otherwise the report rate (15 credits). A refresh re-pulls a report this workspace holds, allowed once it is 14 days old. Returns the app's report preflight and, when the report can be loaded, a quote_token (5 minutes, this key only) for purchase_creator_report with the same run_id, result_id, calculation_method and refresh. Requires discovery:spend, an admin or manager member with Discovery access. Another workspace's run or result is 404.

MCP tool

preflight_creator_report

Scopes

discovery:spend

Members

admin, manager

Idempotency-Key

Ignored (read)

Rate weight

1

Free. Price a contact unlock (1 credit per email; pricing provisional) and get the quote_token unlock_creator_contacts needs. The quote_token is valid 5 minutes, only for this key and its member and exactly this request; pass the same fields to unlock_creator_contacts. Calls the paid-provider gate first (503 while live provider calls are switched off, 403 when the member may not spend). Requires discovery:spend, an admin or manager member with Discovery access.

MCP tool

preflight_contact_unlock

Scopes

discovery:spend

Members

admin, manager

Idempotency-Key

Ignored (read)

Rate weight

1

Looks up which creator profiles registered each email (up to 100 emails), presenting the quote_token from preflight_contact_unlock. 1 credit per email. Pricing is provisional (it follows the metering catalog's rate card, so the daily credit cap bounds provider spend). Profile names and handles are authored by the creators: labelled untrusted. The charge is keyed by the quote's signed provider request, so a retry is never charged twice; a provider failure releases the credits. By default it runs within the credential's daily Discovery-credit cap (429 daily_credit_cap_reached). When the credential asks for approval in TLNT for Discovery credits, the lookup is queued for an admin instead (202 pending_approval; once executed, read the result with get_discovery_spend_result). 409 quote_expired / quote_invalid / quote_stale: preflight again; 402 insufficient_credits. Requires discovery:spend, an Idempotency-Key, an admin or manager member with Discovery access.

MCP tool

unlock_creator_contacts

Scopes

discovery:spend

Members

admin, manager

Approval

Runs directly; queued when the credential asks for approval for discovery_spend

Idempotency-Key

required

Rate weight

5

Untrusted fields

data

Free. Price an audience overlap (15 credits; pricing provisional) and get the quote_token get_audience_overlap needs. The quote_token is valid 5 minutes, only for this key and its member and exactly this request; pass the same fields to get_audience_overlap. Calls the paid-provider gate first (503 while live provider calls are switched off, 403 when the member may not spend). Requires discovery:spend, an admin or manager member with Discovery access.

MCP tool

preflight_audience_overlap

Scopes

discovery:spend

Members

admin, manager

Idempotency-Key

Ignored (read)

Rate weight

1

Measures how much the audiences of 2 to 10 Instagram or YouTube creators overlap (each creator's overlapping and unique share, and the totals), presenting the quote_token from preflight_audience_overlap. 15 credits. Pricing is provisional (it follows the metering catalog's rate card, so the daily credit cap bounds provider spend). Usernames are authored by the creators: labelled untrusted. The charge is keyed by the quote's signed provider request, so a retry is never charged twice; a provider failure releases the credits. By default it runs within the credential's daily Discovery-credit cap (429 daily_credit_cap_reached). When the credential asks for approval in TLNT for Discovery credits, the lookup is queued for an admin instead (202 pending_approval; once executed, read the result with get_discovery_spend_result). 409 quote_expired / quote_invalid / quote_stale: preflight again; 402 insufficient_credits. Requires discovery:spend, an Idempotency-Key, an admin or manager member with Discovery access.

MCP tool

get_audience_overlap

Scopes

discovery:spend

Members

admin, manager

Approval

Runs directly; queued when the credential asks for approval for discovery_spend

Idempotency-Key

required

Rate weight

5

Untrusted fields

data

Free. Price a collaborations lookup (3 credits; pricing provisional) and get the quote_token get_creator_collaborations needs. The quote_token is valid 5 minutes, only for this key and its member and exactly this request; pass the same fields to get_creator_collaborations. Calls the paid-provider gate first (503 while live provider calls are switched off, 403 when the member may not spend). Requires discovery:spend, an admin or manager member with Discovery access.

MCP tool

preflight_creator_collaborations

Scopes

discovery:spend

Members

admin, manager

Idempotency-Key

Ignored (read)

Rate weight

1

Lists the brand collaborations of a creator (or the creators of a brand): kind posts (the sponsored posts, up to 30, optionally between created_after_ms and created_before_ms) or summary (counts per counterpart, up to 10), presenting the quote_token from preflight_creator_collaborations. 3 credits. Pricing is provisional (it follows the metering catalog's rate card, so the daily credit cap bounds provider spend). Post text and names are authored outside the agency: labelled untrusted. The charge is keyed by the quote's signed provider request, so a retry is never charged twice; a provider failure releases the credits. By default it runs within the credential's daily Discovery-credit cap (429 daily_credit_cap_reached). When the credential asks for approval in TLNT for Discovery credits, the lookup is queued for an admin instead (202 pending_approval; once executed, read the result with get_discovery_spend_result). 409 quote_expired / quote_invalid / quote_stale: preflight again; 402 insufficient_credits. Requires discovery:spend, an Idempotency-Key, an admin or manager member with Discovery access.

MCP tool

get_creator_collaborations

Scopes

discovery:spend

Members

admin, manager

Approval

Runs directly; queued when the credential asks for approval for discovery_spend

Idempotency-Key

required

Rate weight

5

Untrusted fields

data

Schedules one of your own saved searches to run daily or weekly. Each scheduled run spends Discovery credits like a search, capped at the saved search's current uncached price per run, and is charged to THIS credential's daily Discovery credit cap when it runs: a run that would pass the cap is skipped (not charged), and the schedule stops when the API key or connection is revoked or expires or its member is deactivated. In the "Discovery credits" approval class: by default it is scheduled at once — the price per run is computed now and also counts against today's credit cap (429 daily_credit_cap_reached past it, nothing scheduled) — and answers 200 { status: "scheduled", data: { preset_id, schedule_frequency, schedule_next_run_at } }. When the credential asks for approval in TLNT for Discovery credits, it is queued for an admin instead (202 pending_approval; the approver sees the price per run; poll get_action). Turn it off at once with unschedule_discovery_preset. Only the saved search's owner can schedule it (403); another workspace's id or another member's private saved search is 404. Requires discovery:spend, an Idempotency-Key, an admin or manager member with Discovery access.

MCP tool

schedule_discovery_preset

Scopes

discovery:spend

Members

admin, manager

Approval

Runs directly; queued when the credential asks for approval for discovery_spend

Idempotency-Key

required

Rate weight

1

For a paid Discovery call THIS key queued for approval: once an admin approved it and it ran (get_action status executed), returns what it produced — the search's discovery_run_id, the report's result_id (read it free with get_creator_report), a lookup's data (contact unlock, audience overlap, collaborations), the script job, or the schedule — and the credits it charged. Before that, result is null and status says where it is. Another credential's or workspace's action id is 404. Lookup data is authored outside the agency: labelled untrusted. It is kept for the Modash data-retention window (30 days, result_expires_at); after that the result carries result_expired: true and no data.

MCP tool

get_discovery_spend_result

Scopes

discovery:read

Members

admin, manager, scout, viewer

Idempotency-Key

Ignored (read)

Rate weight

1

Untrusted fields

result