The tools
| Tool | Use it to | Charged for |
|---|---|---|
capabilities | read vocabularies, band boundaries, limits and disclosure rules | free |
usage | see 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 held | free |
guide | read this guide in full | free |
send_ | tell the Megido team about a bug, wrong or missing data, or something you need | free, within a daily limit |
search_ | find niches by words or by niche conditions: size, level, median index, share of growing members, leading country | base + first-seen niches |
get_ | open one niche: distributions, hierarchy (parent, children, neighbors), a stable sample of members | base + first-seen niches and sample members |
search_ | find projects by an idea, by similarity to projects you hold, or by conditions on quality axes, scale, growth, country, type and niche | base + first-seen projects |
get_ | open projects: index with an explanation of each axis, niches at every level, nearest neighbors | base + first-seen niches and neighbors |
lookup_ | check whether domains you already have are in the corpus | base per distinct domain |
reveal_ | turn project ids into domains with the other domains and the payment service | base + reveal per new project |
get_ | visits, uniques, engagement, devices, top countries and their changes | base + audience part per new project + exact surcharge |
get_ | traffic sources and social platforms | base + channels part per new project + exact surcharge |
get_ | branded split, top organic queries, paid queries | base + 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
capabilitiesrather than guessing. - Text and seeds return the closest matches in meaning. Sorting then reorders only the closest results,
relevance_poolprojects insearch_projectsandrelevance_pool_cohortsniches insearch_cohorts(seecapabilities); 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 (limitmay change). Each page is a call of its own, with the base price and first-seen prices for its new rows. Paging stops atcursor_depthrows (seecapabilities); narrow the conditions to reach others.search_projectsalso takesexclude, the ids of projects you have already seen, to leave them out. - Steer a search away.
search_projectstakesanti_seed: projects the results should not resemble. It needs text or a seed. - Choose the niche sample. By default the sample of
get_cohortis 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, andsample_limitsets how many, up to the sample limit incapabilities. - Retry safely. Pass an idempotency key with a paid call, as
_meta.idempotency_keyover MCP or theIdempotency-Keyheader 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 aquote_tokenagain 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_cohorttakesparts(distributions,sample,hierarchy) andget_project_cardtakesparts(description,index,cohorts,neighbours); withoutpartsboth 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_domainstrips a scheme, a path, a leadingwwwand 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_projectis 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.