Works in any folder
Research needs no vfrey project.ingest and creators find|search|show run from any folder, and they write only the files you ask for: no vfrey.json, scenes/, scripts/, videos/ or skill copies. Do not run init for research. Outside a project the command is npx @vfrey/vfrey ingest ... (the hints vfrey prints already say so); inside one, npx vfrey ... works too.
Cost first
--quote prices every step and runs nothing. A plan that can use more than 10 credits does not run until you accept the cost with --max-credits N (or budget.maxCredits in the plan); without it vfrey prints the quote and stops. Each provider call is 1 credit: one page of a search, one trending read, one user search, one profile, or one creator’s recent posts. A call that fails costs nothing. The balance must cover the worst case before the first call, a plan makes at most 100 calls, and a retry of the same request is not charged twice. See Plans and credits.
The plan
A plan is JSON.npx vfrey ingest schema prints this format, --recipe ID prints a worked plan, and --json prints the full JSON Schema.
A plan is checked before anything is sent, and a mistake names the field:
collect[0].pages: Too big: expected number to be <=5.
Files
--out DIR writes everything in one folder; the other flags write one file each (a flag next to --out puts that file where it says).
A spreadsheet never runs text that starts like a formula: a caption that starts with
=, +, - or @, or with a tab, is written with a leading apostrophe. Handles and group names are written without @, so they never need one.
What comes back
Metrics
Accounts that are not creators
Every creator gets an account type from its name, handle, bio and the platform’s own business label:creator, official (the brand’s own account, when the name carries a mustMention word and the account says so), retail (malls and shops) or business. A creator is also flagged probably not a creator when it looks like a media or news page, a betting or spam promo, or has very low engagement on huge views. The report hides everything but creators until you turn the chips on, and the terminal lists the others apart. city comes only from a caption, name or bio that mentions it. Cities, retail words and media words come from a language pack; Vietnamese is the first.
Language
country and region say where a post was published, not what language it is: a Lao caption can be published from Vietnam. Set filter.languages (["vi"] for Vietnamese) to keep only captions in those languages. Posts in another language are dropped and counted; posts whose language the source did not say are kept and counted, and the summary says how many. The flag is --language vi on creators find and ingest trends. The sale recipe below sets it for Vietnam.
Failed calls
A call that fails is skipped and not charged. The terminal,summary.md and the report’s method note say which step and search it was, the page, and why, in plain words: Step s1 (search on TikTok): the search "muji haul" (page 2) took too long to answer. It was skipped and not charged, so its posts are missing. The reasons are took too long, was busy, could not be reached, sent an answer vfrey could not read, or could not answer this request. The same detail is in summary.steps[].failures of the JSON.
Limits that are said out loud
- Country. TikTok keyword search can be limited to a country, and posts whose own country differs are dropped and counted. Hashtag search and Instagram search cannot be limited to a country; the result says so in a
Note:line and, where a post shows its country, filters on it. - Pages. Each page is one call. Some searches return one page only.
- Platforms. A platform the server cannot search makes no call and costs nothing; the step says so.
- One plan, one run. At most 100 calls, 12 steps, 12 queries a step. Six runs a minute.
The HTML report
--html FILE (or --out DIR) writes one file with the data inside, so it works offline (the fonts load from the web when you are online and fall back to system fonts). It has a summary strip, two views (every post with an Open post link, and the groups with expandable post lists), chips for account type and follower tier, filters for city, followers, posts per creator, views, date, search and platform, sorting on any number column, Copy as CSV, light and dark themes, and a method note that lists what the plan did in plain words. It works at phone width. --open opens it.
Recipes
KOLs for a brand sale in a country
Use it for creators, KOLs or influencers who post about a brand, a sale or a campaign in one country.Competitor content monitoring
Use it for what the competitors post and what performs, from the brands’ own accounts.Trend scouting in a region, by hashtag
Use it for what is trending or rising in a niche or a country; use group sound for the sounds instead.A creator deep dive
Use it for everything about one creator: numbers, recent posts, formats, hooks, best hours.Cross-platform topic research
Use it for what people post about a topic across TikTok, YouTube and Reddit; group by day to see when it moves, or by creator to see who.Your agent
The vfrey skill carries these recipes and the whole flow: expand your words into 5 to 10 searches in the local language, write the plan (settingfilter.languages from your request, and withinDays for a seasonal campaign such as Black Friday, saying what dates the posts span), quote and ask you to confirm the cost, run once with --out, read summary.md, open the report, and summarise with links: best bets, by city, viral but small, and the accounts that are probably not creators. See Your agent.