Tool reference

The server lists only the tools your connection may use (see Permissions), so tools/list can show fewer tools than this page. AI apps call tools for you; this page is for checking what a tool does, and for calling the server yourself.

Conventions

• Tool names are kebab-case (get-dataset-items). Arguments and result fields are snake_case (run_id, wait_secs). Protocol keys such as inputSchema and isError keep their MCP names.
• Each tool has annotations: readOnlyHint: true on tools that only read, destructiveHint: true on tools that stop or delete, openWorldHint: true on tools that start billed runs. Clients use them to decide when to ask you first.
• A result comes back twice: as JSON text in content, and as an object in structuredContent.
• A refusal (bad argument, missing permission, not found, out of credit) is a normal result with isError: true and the reason as text. An unknown tool name is a JSON-RPC error -32602.
• Results that list items are trimmed to about 100 KB, with truncated: true when items were left out. Ask for fewer items, fewer fields, or the next offset.

Calling a tool

tools/call over HTTP

curl https://lantfly.com/mcp \
  -H "Authorization: Bearer $LANTFLY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": { "name": "list-runs", "arguments": { "limit": 2, "status": ["SUCCEEDED"] } }
  }'

Answer

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{ "type": "text", "text": "{\n    \"total\": 41,\n    \"offset\": 0,\n    \"items\": [ … ]\n}" }],
    "structuredContent": { "total": 41, "offset": 0, "items": [ { "id": "6f1c…", "status": "SUCCEEDED" } ] },
    "isError": false
  }
}

A refusal

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{ "type": "text", "text": "This API token does not have the runs.read permission." }],
    "isError": true
  }
}

The run object

Run tools return a run with these fields:

Field	Description
id	Run ID.
actor_id, actor_slug	The actor.
status	READY, RUNNING, SUCCEEDED, FAILED, TIMED-OUT or ABORTED.
status_message	The actor's latest status message.
started_at, finished_at	ISO 8601 timestamps.
stats	Run time, compute units, result count.
default_dataset_id	Dataset with the run's results.
default_key_value_store_id	Key-value store with INPUT, OUTPUT and other records.
usage_total_usd	Cost of the run so far.

Actors and runs

Tool	What it does	Token permission	Organization role
search-actors	Find actors you can run	actors.read
get-actor-details	README, input schema, example input	actors.read
call-actor	Run an actor and wait for results	actors.run, not read-only	Start runs
get-run	A run's status, optionally waiting	runs.read
list-runs	Recent runs	runs.read
get-run-log	A run's log	runs.read
abort-run	Stop a run	runs.write, not read-only	Manage runs
get-dataset-items	Read a dataset	storages.read (and runs.read with run_id)
get-key-value-record	Read a key-value record	storages.read

Token permissions matter only for permission-limited tokens; full-access tokens and OAuth connections have them all. Organization role permissions apply when you act for an organization.

search-actors

Finds actors you can run: your own, shared with you, and public ones. Deprecated actors are left out. Results are ordered by number of runs.

Argument	Type	Default	Description
query	string		Words to find in the slug, title or description. Empty lists everything.
limit	integer, 1–50	10
offset	integer ≥ 0	0
my	boolean	false	Only actors owned by the account.

Result: total, offset, items[] with id, slug, title, description, is_public, total_runs.

Arguments

{ "query": "tiktok", "limit": 5 }

get-actor-details

An actor's description, README (first 8,000 characters), input schema and example input. Call it before call-actor so the AI builds a valid input.

Argument	Type	Required	Description
actor	string	Yes	Actor ID, slug (user~name or user/name) or alias.

Result: id, slug, title, description, readme, version, inputSchema (JSON Schema of the input object), example_input, default_run_options (memory_mb, timeout_secs).

Arguments

{ "actor": "lantfly~tiktok-scraper" }

call-actor

Starts a run with the given input and waits for it, up to wait_secs. Returns the run and its first dataset items. A run still going when the wait ends keeps running: follow it with get-run and read results with get-dataset-items. Runs are billed to the account. Not available to read-only connections.

Argument	Type	Default	Description
actor	string	Required	Actor ID, slug or alias.
input	object	{}	The actor input, as its input schema describes.
wait_secs	integer, 0–120	120	How long to wait for the run to finish. 0 returns at once.
preview_items	integer, 0–100	10	How many dataset items to return.
memory_mb	integer ≥ 128	Actor default	Memory of the run.
timeout_secs	integer ≥ 10	Actor default	Run timeout.
max_items	integer ≥ 1		Most results a pay-per-result actor may charge for.
build	string	Latest	Version or tag to run.

Result:

Field	Description
run	The run object.
finished	Whether the run had finished when the tool returned.
item_count	Items in the run's dataset so far.
items	Up to preview_items items.
truncated	true when the dataset holds more than items.
next	A hint for the AI: how to read the rest, or how to follow a run still going.

Arguments

{
  "actor": "lantfly~tiktok-scraper",
  "input": { "hashtags": ["skincare"], "resultsPerPage": 20 },
  "wait_secs": 90,
  "preview_items": 5
}

Refusals: invalid input (with the field errors), out of usage or credit, too many runs at once, a read-only connection, a role without Start runs, an actor you can't run, or more than 3 runs in one request.

get-run

Status and details of a run, optionally waiting for it to finish.

Argument	Type	Default	Description
run_id	string	Required
wait_secs	integer, 0–120	0	Wait up to this long for the run to finish. Ignored when it has finished.

Result: run, finished, item_count, next.

list-runs

The account's runs, newest first.

Argument	Type	Default	Description
actor	string		Only runs of this actor (ID, slug or alias).
status	array of strings		Only these statuses: READY, RUNNING, SUCCEEDED, FAILED, TIMED-OUT, ABORTED.
limit	integer, 1–50	10
offset	integer ≥ 0	0

Result: total, offset, items[] of run objects.

get-run-log

A run's log with secrets masked: by default its last tail_kb kilobytes, or from a byte offset to follow a run that's still going.

Argument	Type	Default	Description
run_id	string	Required
tail_kb	integer, 1–100	20	How much log to return, in KB.
from	integer ≥ 0		Read forward from this byte offset instead of the tail.

Result: run_id, status, finished, log (text), from (where the text starts), next_offset (pass as from next time), total_bytes.

abort-run

Stops a run that's still going. Results it already saved stay. Not available to read-only connections.

Argument	Type	Required
run_id	string	Yes

Result: run, already_finished (true when the run had already ended).

get-dataset-items

Reads items of a dataset, a page at a time. Pass dataset_id, or run_id to read that run's default dataset.

Argument	Type	Default	Description
dataset_id	string		Dataset ID, for example a run's default_dataset_id.
run_id	string		Or the run whose default dataset to read.
offset	integer ≥ 0	0
limit	integer, 1–200	20
fields	array of strings		Only these top-level fields.
omit	array of strings		Leave these top-level fields out.
desc	boolean	false	Newest items first.

Result: dataset_id, total, offset, count, truncated, items.

Arguments

{ "run_id": "6f1c…", "limit": 50, "fields": ["url", "text", "likes"] }

get-key-value-record

A record of a key-value store: a run's OUTPUT, INPUT, screenshots and so on. Pass store_id, or run_id for that run's default store.

Argument	Type	Default	Description
store_id	string		Key-value store ID.
run_id	string		Or the run whose default store to read.
key	string	OUTPUT	Record key.

Result: store_id, key, content_type, size_bytes, then one of:

• value: the parsed JSON, for JSON records;
• text and truncated: for text, XML and large JSON;
• note: for binary content, which isn't returned. Open it from the Console or the API.

Per-actor tools

Add ?actors= to the server address with up to 20 actor slugs or IDs, comma separated:

Address

https://lantfly.com/mcp?actors=lantfly~tiktok-scraper,lantfly~web-scraper

Each actor you can see becomes a tool:

• Name: the slug with ~ replaced by -- (and other characters outside A-Za-z0-9_- by -), for example lantfly--tiktok-scraper.
• Arguments: the actor's input schema, turned into JSON Schema.
• Behavior: like call-actor with those arguments as the input: it waits up to 120 seconds and returns the run and its first results.
• Needs: the same as call-actor. Read-only connections don't get these tools.

Social listening

These tools appear when your connection can read social listening: the token has listening.read (or full access), your organization role has View social listening, and the token isn't limited to actors. Tools that change something also need listening.write and a connection that isn't read-only.

Inside a project, your project role decides what you may do, as in the Console:

Project role	May
viewer	Read everything in the project.
analyst	Also label and verify mentions, update leads, save audience estimates.
manager	Also change settings, sources, attributes, campaigns, alerts and reports, and collect now.

The role is checked on each call. Call get-my-project-access first to know it.

Agent tools

Built for an AI working through a project: read compact mentions and authors, analyse them, and write the results back.

list-listening-projects

The account's projects (up to 100), newest first.

Argument	Type	Description
status	string	active, paused, completed or stopped.

Result: items[] with id, name, status, sources, mentions (counts).

search-mentions

Posts, comments and reviews a project collected, newest or most engaging first. Hidden mentions are left out.

Argument	Type	Default	Description
project_id	string	Required	From list-listening-projects.
query	string		Words that must all appear in the text.
platform	string		tiktok, instagram, facebook, youtube, threads, x, pinterest, lemon8, reddit, telegram, shopee, tiki, lazada, tiktok_shop, google_maps, app_store, google_play, news, forum.
kind	string		post, comment or review.
sentiment	string		positive, neutral, negative or unknown (no label).
intent	string		provider, seeker, general or unknown.
author	string		Author handle, exact (a leading @ is ignored).
from, to	string		Published on or after / on or before, YYYY-MM-DD or ISO 8601.
sort	string	published_at	published_at or engagement.
limit	integer, 1–50	20
offset	integer ≥ 0	0

Result: project (id, name), total, offset, items[] with id, platform, kind, url, author, author_name, text (up to 1,000 characters), hashtags, published_at, views, likes, comments, shares, engagement, sentiment, intent, intent_source (ai, rule or manual), attributes (names), is_irrelevant.

Arguments

{ "project_id": "0b6e…", "sentiment": "negative", "from": "2026-10-01", "sort": "engagement", "limit": 20 }

list-attributes

A project's attributes (topics, product lines, topic clusters, tracking terms) with how many mentions carry each.

Argument	Type	Required
project_id	string	Yes

Result: items[] with id, name, type, mentions. Use id with label-mentions tag and untag.

list-authors

Distinct authors of a project in a period, most mentions first. Public data only, with no label about the person.

Argument	Type	Default	Description
project_id	string	Required
from	string	30 days before to	First day, YYYY-MM-DD, project timezone.
to	string	Today	Last day, YYYY-MM-DD.
platform	string		One platform (values as in search-mentions).
limit	integer, 1–100	50
offset	integer ≥ 0	0

Result: project, from, to, total, offset, items[] with platform, handle, name (public display name), location (public profile location), is_person (false for pages, news sites, the brand's own accounts and Facebook page posts), mentions, sample_text (up to 300 characters).

get-audience

The aggregate audience of a project and period: Lantfly's own estimate (gender from display names, province from public profile locations) and the latest estimates saved with save-audience-estimate that overlap the period. Groups under 10 authors are null.

Argument	Type	Default
project_id	string	Required
from	string	30 days before to
to	string	Today

Result: project, from, to, lantfly (the built-in estimate), agent_estimates[] (up to 5, newest first).

label-mentions

Corrects up to 200 mentions of a project in one call, as a person would in the Console. One action per call. Needs listening.write and the analyst role; irrelevant and relevant need the verify right on the project and are recorded in the review trail.

Argument	Type	Required	Description
project_id	string	Yes
action	string	Yes	set_sentiment, set_intent, tag, untag, irrelevant, relevant, hide, show.
ids	array of integers, 1–200	Yes	Mention IDs from search-mentions.
sentiment	string or null	With set_sentiment	positive, neutral, negative, or null to clear.
intent	string or null	With set_intent	provider, seeker, general, or null to clear. Saved as a manual label the built-in AI never replaces.
attribute_id	integer	With tag, untag	From list-attributes.

Result: project, action, affected.

Arguments

{ "project_id": "0b6e…", "action": "set_sentiment", "ids": [918273, 918280], "sentiment": "negative" }

irrelevant takes mentions out of analytics and reports; relevant puts them back.

save-audience-estimate

Saves an aggregate audience estimate the AI made for a project and period: how many distinct authors it looked at, and how many of them it judges female or male and in each age band. Counts only: the tool takes no label per person. Needs listening.write and the analyst role.

Argument	Type	Required	Description
project_id	string	Yes
from, to	string	Yes	The period analysed, YYYY-MM-DD.
authors	integer ≥ 10	Yes	Distinct authors looked at; at most the project's authors in the period (total of list-authors).
gender	object	Yes	female and male, integers ≥ 0. Their sum can't exceed authors.
age	object	Yes	Authors per band: under_18, 18_24, 25_34, 35_44, 45_plus. Bands left out count as 0. The sum can't exceed authors.
method	string, 10–500 characters	Yes	How the estimate was made (signals, model). Shown to the team.

Authors the AI can't judge stay out of the counts. Leave pages, shops and news sites out. On the project dashboard, groups under 10 authors are hidden.

Result: project, estimate.

Arguments

{
  "project_id": "0b6e…",
  "from": "2026-10-01",
  "to": "2026-10-31",
  "authors": 240,
  "gender": { "female": 151, "male": 62 },
  "age": { "18_24": 96, "25_34": 88, "35_44": 21 },
  "method": "Display names, profile bios and writing style of each author; Claude, no external data."
}

API tools

Each of these tools calls one /api/v3/listening endpoint as you, with the same checks and validation as the API. Path values become arguments (project_id, mention_id…); other arguments go to the query string (reads) or the JSON body (writes). The result is the endpoint's JSON (data, and meta for lists), or { "ok": true } when the endpoint answers with no body. Endpoint details are in the API reference and Listening API.

• Reads need listening.read; writes need listening.write and a connection that isn't read-only.
• An API error (403, 404, 422 with field errors) comes back as isError with the API's message.
• An answer over 200 KB is refused with a hint to lower per_page or narrow the filter.
• Endpoints that return files (exports, downloads) aren't tools.

Common arguments:

Argument	Type	Description
page, per_page	integer; per_page 1–100, default 25	Paging, on list tools that take it.
from, to	string	YYYY-MM-DD, project timezone. With from/to, days is ignored.
days	integer, 1–366, default 30	The last N days, when from/to are left out.
platform	array of strings	Platforms, values as in search-mentions.
sentiment	string	positive, neutral, negative, unknown.
kind	string	post, comment, review.
q	string	Words in the text.
author	string	Author handle.
attribute	array of integers	Attribute IDs.

"Analytics filters" below means from, to, days, platform, sentiment, kind, q, author, attribute.

Projects

Tool	Role	Arguments	Does
get-listening-project	viewer	project_id	A project's settings: keywords, brands, languages, timezone, schedule, status, counts.
get-my-project-access	viewer	project_id	Your role (viewer, analyst, manager) and can (view, analyze, verify, manage).
create-listening-project	Manage social listening in an organization	name (required), description, include_keywords, exclude_keywords, contextual_keywords, context_keywords, brands (up to 10 name + keywords), languages, category, track_from, track_until, interval_minutes (15–10080), timezone, collect_comments, backfill_days	Creates a project. Counts against the plan's project limit. Add sources, then collect.
update-listening-project	manager	project_id plus any field of create-listening-project except backfill_days	Changes settings. Send only what changes.
set-project-status	manager	project_id, move (pause, resume, stop)	Pauses or resumes scheduled collection, or ends the project.
collect-project-now	manager	project_id, add_keyword_sources (boolean, default true)	Collects every active source now. Billed.

Sources

Tool	Role	Arguments	Does
list-sources	viewer	project_id, q, platform, state (on, off, problem), page, per_page	What the project collects from, with state and last collection.
list-collections	viewer	project_id, page, per_page	Recent collection runs: when, which sources, how many mentions, errors.
suggest-sources	viewer	project_id	Hashtags, profiles and keywords the mentions point to that the project doesn't follow yet.
add-source	manager	project_id, platform, kind (keyword, hashtag, profile, url…, depending on the platform), value (up to 500 characters), results_limit, plus other source settings the API takes	Follows a new source.
update-source	manager	project_id, source_id, value, results_limit, is_active, plus other source settings	Changes a source or turns it on or off.
bulk-sources	manager	project_id, ids (up to 200), action (enable, disable, collect, delete, results_limit, review_stars), results_limit, review_stars (1–5)	Acts on many sources. collect is billed.
delete-source	manager	project_id, source_id	Stops following a source. Collected mentions stay.
import-posts	manager	project_id, urls (up to 100)	Collects specific posts by URL. Billed.

Mentions

Tool	Role	Arguments	Does
get-mention	viewer	project_id, mention_id	One mention in full: text, author, metrics, media, sentiment, intent, attributes, comments, review history.
update-mention	analyst	project_id, mention_id, is_hidden, sentiment (or null), intent (or null)	Corrects one mention. A manual intent is never overwritten by the built-in AI. For many, use label-mentions.

Analytics

Tool	Role	Arguments	Does
get-project-dashboard	viewer	project_id, analytics filters, compare_from, compare_to	Totals, sentiment, share of voice, platforms, timeline and top posts, optionally against a comparison period.
get-hashtag-trends	viewer	project_id, analytics filters, limit (1–100, default 20)	Hashtags with counts and growth.
get-topics	viewer	project_id, analytics filters, limit (1–150, default 80), buzz (only words that grew)	Most used words and phrases, with sentiment.
get-peaks	viewer	project_id, analytics filters	Days with unusually many mentions, and what drove them.
list-influencers	viewer	project_id, analytics filters, sort (mentions, interactions, posts, shares, views, followers, negative, positive), direction (asc, desc), page, per_page	Authors ranked.
compare-listening-projects	viewer of each	projects (2–5 project IDs, required), from, to, days	Side-by-side totals, sentiment and timeline.
list-audience-estimates	viewer	project_id	Aggregate estimates saved for the project, newest first.
delete-audience-estimate	analyst	project_id, estimate_id	Removes an estimate.

Attributes

Tool	Role	Arguments	Does
create-attribute	manager	project_id, name (required, up to 60), type (attribute, product_line, topic_cluster, tracking_term), color (#RRGGBB), rules (auto-tagging: match any or all, conditions of field and values)	A new attribute to tag mentions with.
update-attribute	manager	project_id, attribute_id, same fields	Renames or changes an attribute.
delete-attribute	manager	project_id, attribute_id	Deletes an attribute and its tags on mentions.

Creators and leads

Tool	Role	Arguments	Does
list-creators	viewer	project_id, q, platform, sort, page, per_page, plus other filters the API takes	Creators (KOL, KOC) who posted about the project, with followers, posts, views and engagement.
get-creator	viewer	project_id, creator_id, sort (published_at, views, engagement)	A creator's profile and posts in the project.
track-creator	manager	project_id, creator_id	Follows the creator's profile as a source.
untrack-creator	manager	project_id, creator_id	Stops following it.
list-leads	viewer	project_id, status (new, contacted, qualified, ignored), platform, kind (post, comment), assignee_id, q, from, to, page, per_page	Mentions from people who want to buy (intent seeker), as a sales inbox.
update-lead	analyst	project_id, lead_id, status, assignee_id (or null), note (up to 2,000, or null)	Sets a lead's status, assignee or note.

Campaigns, alerts and reports

Tool	Role	Arguments	Does
list-campaigns	viewer	project_id	Campaigns with dates, budget and results.
get-campaign	viewer	project_id, campaign_id	A campaign's report: reach, views, engagement, EMV, cost per result, top posts.
list-campaign-mentions	viewer	project_id, campaign_id, sort (published_at, views, engagement), platform, page, per_page	Posts counted in a campaign.
create-campaign	manager	project_id, name and starts_on (required), description, ends_on, budget_usd, hashtags, keywords, creators (handles, up to 500), report_show_costs	A new campaign.
update-campaign	manager	project_id, campaign_id, same fields	Changes a campaign. Send only what changes.
delete-campaign	manager	project_id, campaign_id	Deletes a campaign. Mentions stay.
list-alerts	viewer	project_id	Alert rules of the project.
create-alert	manager	project_id, type (required: viral, negative, creator_post, volume_spike, lead, low_rating), name, is_active, params	A new alert rule. params: viral takes views, growth_pct, min_views; creator_post takes handles; volume_spike takes multiplier, min_mentions; low_rating takes max_rating; negative and lead take none.
update-alert	manager	project_id, alert_id, name, is_active, params	Changes an alert rule or turns it on or off.
delete-alert	manager	project_id, alert_id	Deletes an alert rule.
list-reports	viewer	project_id	Reports generated for the project.
get-report	viewer	project_id, report_id	A report's summary, figures and highlights.
create-report	manager	project_id, from and to (required), title (up to 160)	Generates a report in the background; read it with get-report.

Verify queue

Tool	Role	Arguments	Does
list-verify-queue	verify right	project_ids, status (unverified, verified, irrelevant, all), type (post, comment), sentiment, intent, platform, q, from, to, page, per_page	Mentions waiting for a person to verify, across the projects you may verify.
get-verify-stats	verify right	project_ids, from, to	Verified, irrelevant and waiting counts per project.
verify-mentions	verify right on each project	mention_ids (required), action (required: verify, unverify, sentiment, intent, irrelevant, relevant, note), sentiment (positive, neutral, negative), intent (provider, seeker, general), note (up to 2,000)	Verifies mentions or corrects them; recorded in the review trail.

The verify right comes with the analyst or manager project role, or the Verify mentions organization permission.

Not available over MCP

Deleting or transferring a project, sharing and guests, project members, data source credentials, public share links, and file exports are left out on purpose. Use the Console or the API.

Related

• Permissions
• Examples
• Troubleshooting