Skip to main content

Working with the tools

A recommended order for an agent:

  1. Call capabilities once per session and keep its vocabularies and limits.
  2. Call usage before any wide search to check available credits and coverage.
  3. If the user cannot yet name a company, start with search_cohorts. Many market questions are answered by get_cohort with parts: ["distributions"] alone, without listing any site.
  4. Move to search_projects with filters and a small limit. Read the descriptions and drop what is off-topic before revealing anything.
  5. Use estimate: true before any call that may show many new entities, and stop if the price or the coverage does not fit the question.
  6. Reveal only the projects the user needs named.
  7. Buy profile parts in bands first. Ask for precision: exact only when the user needs exact numbers, and keep the result: the surcharge applies again on every exact call.
  8. When the user already has domains, use lookup_domain instead of searching.
  9. 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.

RefusalWhenWhat to do
unknown_filter_valuea filter value is not in the vocabularypick one of the nearest accepted values it lists
coverage_exceededthe call would show more new niches or projects than the coverage left this periodset the parameter named in fitting_param to fitting_limit, or for a list of ids or domains keep its first fitting_limit items; 0 means even the fixed part does not fit: ask for fewer parts, or wait for the next period
insufficient_balanceyour available credits do not cover the calltell your user; an owner of your organization tops up at top_up_url
sign_up_requiredyour account has no registration and the tool needs oneask your user to register at sign_up_url, a link that works once, in any browser, for 30 minutes: the same account and connection keep working
quota_exhaustedthe free quota of your plan does not cover a call of an index tool, and the available credits do not cover the restwhen fitting_limit is present, set fitting_param to it; without registration, ask your user to register at sign_up_url; otherwise wait for renews_on, or tell your user that an owner tops up at top_up_url
limit_exceededa limit is passed: list size, batch size, sample size, cursor depth, the daily feedback limit or the hourly limit of task messagesstay within max; past a daily or hourly limit, wait
confirmation_requiredthe call costs credits, and your organization requires an estimate for this tool or for a call that may cost more than estimate_required_abovethe refusal carries the estimate: show your user the price and run it with its quote_token
quote_expiredthe estimate is no longer validestimate again
quote_spentthe estimate has already run and its replay has endedestimate again
quote_outdatedthe estimate counted on more free quota than is left nowestimate again
layer_unavailablea part of the corpus is not available now or for this entity, such as text search while it is downuse 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 questionPath
"Is anyone already doing X, and who?"search_cohorts with a short description, search_projects with the same text and a small limit, reveal the closest few, then get_channels and get_keywords to see how they get users.
"Where is there room near X?"search_cohorts with X to find its niche, get_cohort on it with parts: ["hierarchy"], then search_cohorts 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_domain, then get_audience, get_channels, get_keywords. State that growth covers one month only.
"List sites in niche N with 15–75k visits."search_projects with filters.cohort_id of N and filters.scale_band: ["b15k_75k"], then reveal the ones that match.
"Which niches in market M are growing?"search_cohorts at the level you need, then get_cohort 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_project_card with parts: ["index", "cohorts", "neighbours"], then get_cohort with parts: ["distributions"] on its niche; profile parts for the neighbors in bands.
"Find look-alikes of P, but small."lookup_domain on P if you have only its domain, then search_projects with P's project id as seed and filters.scale_band; reveal candidates and check on their sites whether they are small companies.

View as Markdown