Skip to main content

The tools

ToolUse it toCharged for
capabilitiesread vocabularies, band boundaries, limits and disclosure rulesfree
usagesee your plan and its free quota left, balance, available credits, remaining coverage (as a range), limits, and how many projects are revealed and profile parts heldfree
guideread this guide in fullfree
send_feedbacktell the Megido team about a bug, wrong or missing data, or something you needfree, within a daily limit
search_cohortsfind niches by words or by niche conditions: size, level, median index, share of growing members, leading countrybase + first-seen niches
get_cohortopen one niche: distributions, hierarchy (parent, children, neighbors), a stable sample of membersbase + first-seen niches and sample members
search_projectsfind projects by an idea, by similarity to projects you hold, or by conditions on quality axes, scale, growth, country, type and nichebase + first-seen projects
get_project_cardopen projects: index with an explanation of each axis, niches at every level, nearest neighborsbase + first-seen niches and neighbors
lookup_domaincheck whether domains you already have are in the corpusbase per distinct domain
reveal_projectturn project ids into domains with the other domains and the payment servicebase + reveal per new project
get_audiencevisits, uniques, engagement, devices, top countries and their changesbase + audience part per new project + exact surcharge
get_channelstraffic sources and social platformsbase + channels part per new project + exact surcharge
get_keywordsbranded split, top organic queries, paid queriesbase + keywords part per new project + exact surcharge

Notes that change results or cost:

  • Unknown filter values are rejected with the nearest accepted values. Take values from capabilities rather than guessing.
  • Text and seeds return the closest matches in meaning. Sorting then reorders only the closest results, relevance_pool projects in search_projects and relevance_pool_cohorts niches in search_cohorts (see capabilities); it does not search the whole corpus by that field. To rank a whole niche, filter by the niche instead of describing it in words.
  • Set limit. Without it a call returns as many rows as your list limit allows, and every new row costs the first-seen price.
  • Page through a list. A list that has more rows returns a cursor: repeat the call with the same parameters and the cursor to read the next page (limit may change). Each page is a call of its own, with the base price and first-seen prices for its new rows. Paging stops at cursor_depth rows (see capabilities); narrow the conditions to reach others. search_projects also takes exclude, the ids of projects you have already seen, to leave them out.
  • Steer a search away. search_projects takes anti_seed: projects the results should not resemble. It needs text or a seed.
  • Choose the niche sample. By default the sample of get_cohort is the most typical member of the niche and the core members nearest to it; sample_sort: "index" returns the core members with the highest quality index instead, and sample_limit sets how many, up to the sample limit in capabilities.
  • Retry safely. Pass an idempotency key with a paid call, as _meta.idempotency_key over MCP or the Idempotency-Key header over the HTTP API: a retry with the same key returns the stored answer without charging again while the answer is kept, and the same key with other arguments or on another tool is refused. Running a quote_token again shortly after it ran also returns the stored answer without a second charge. So a call lost to a network error can be retried. Without a key, every call is new.
  • Ask only for the parts you need. get_cohort takes parts (distributions, sample, hierarchy) and get_project_card takes parts (description, index, cohorts, neighbours); without parts both return every part. Distributions of a niche and the index of a project cost only the base price. The sample and hierarchy of a niche, and the niches and neighbors of a project, show new projects and niches, and each of them costs the first-seen price.
  • lookup_domain strips a scheme, a path, a leading www and a trailing dot; other subdomains usually miss. A hit reveals the project, with its other domains and payment service, without the reveal price (see "Anonymous and revealed"); reveal_project is not needed for it.
  • Batches. Card, lookup, reveal and the three profile tools take several ids or domains per call, up to the batch limit in capabilities.

View as Markdown