Working with the tools
A recommended order for an agent:
- Call
capabilitiesonce per session and keep its vocabularies and limits. - Call
usagebefore any wide search to check available credits and coverage. - If the user cannot yet name a company, start with
search_cohorts. Many market questions are answered byget_cohortwithparts: ["distributions"]alone, without listing any site. - Move to
search_projectswith filters and a smalllimit. Read the descriptions and drop what is off-topic before revealing anything. - Use
estimate: truebefore any call that may show many new entities, and stop if the price or the coverage does not fit the question. - Reveal only the projects the user needs named.
- Buy profile parts in bands first. Ask for
precision: exactonly when the user needs exact numbers, and keep the result: the surcharge applies again on every exact call. - When the user already has domains, use
lookup_domaininstead of searching. - When something goes wrong or is missing, send
send_feedback(see "Feedback").
When a call is refused
A refusal names what went wrong and carries what you need to go on.
| Refusal | When | What to do |
|---|---|---|
unknown_ | a filter value is not in the vocabulary | pick one of the nearest accepted values it lists |
coverage_ | the call would show more new niches or projects than the coverage left this period | set the parameter named in fitting_ to fitting_, or for a list of ids or domains keep its first fitting_ items; 0 means even the fixed part does not fit: ask for fewer parts, or wait for the next period |
insufficient_ | your available credits do not cover the call | tell your user; an owner of your organization tops up at top_ |
sign_ | your account has no registration and the tool needs one | ask your user to register at sign_, a link that works once, in any browser, for 30 minutes: the same account and connection keep working |
quota_ | the free quota of your plan does not cover a call of an index tool, and the available credits do not cover the rest | when fitting_ is present, set fitting_ to it; without registration, ask your user to register at sign_; otherwise wait for renews_, or tell your user that an owner tops up at top_ |
limit_ | a limit is passed: list size, batch size, sample size, cursor depth, the daily feedback limit or the hourly limit of task messages | stay within max; past a daily or hourly limit, wait |
confirmation_ | the call costs credits, and your organization requires an estimate for this tool or for a call that may cost more than estimate_ | the refusal carries the estimate: show your user the price and run it with its quote_ |
quote_ | the estimate is no longer valid | estimate again |
quote_ | the estimate has already run and its replay has ended | estimate again |
quote_ | the estimate counted on more free quota than is left now | estimate again |
layer_ | a part of the corpus is not available now or for this entity, such as text search while it is down | use what available lists, or try later |
Beyond these, too many calls in a second get HTTP 429 with Retry-After: wait and call again. A revoked key or a suspended organization gets HTTP 401. Over the HTTP API every refusal also comes with an HTTP status of its own.
Recipes
| User question | Path |
|---|---|
| "Is anyone already doing X, and who?" | search_ with a short description, search_ with the same text and a small limit, reveal the closest few, then get_ and get_ to see how they get users. |
| "Where is there room near X?" | search_ with X to find its niche, get_ on it with parts: ["hierarchy"], then search_ with X and filters.level: 1 to compare nearby narrow niches by size, median index and share of growing members. |
| "Is competitor.com healthy?" | lookup_, then get_, get_, get_. State that growth covers one month only. |
| "List sites in niche N with 15–75k visits." | search_ with filters.cohort_ of N and filters.scale_, then reveal the ones that match. |
| "Which niches in market M are growing?" | search_ at the level you need, then get_ with parts: ["distributions"] for each niche: it shows both the growing and the declining share. Members' last months can differ, so do not read a small difference between niches as a trend. |
| "Where does a site stand among its peers?" | get_ with parts: ["index", "cohorts", "neighbours"], then get_ with parts: ["distributions"] on its niche; profile parts for the neighbors in bands. |
| "Find look-alikes of P, but small." | lookup_ on P if you have only its domain, then search_ with P's project id as seed and filters.scale_; reveal candidates and check on their sites whether they are small companies. |