POST /v1/discover answers: which companies match these filters, and who works there? Send account filters and, if you want people too, contact filters. Use it to build a new list. Use count_only first to see how many companies match before anything is delivered.
200
Emails are returned masked today: the first character and the domain are kept.
Request
Send this to also get people inside the companies delivered. Needs
job_title or a readable job_level.When
true, nothing is delivered and nothing is charged. The reply says how many companies match and which source would be asked.Why you are asking. One of
b2b_outbound, ad_audience, own_customer_enrichment, fraud_check. The call is refused if your workspace has not allowed the purpose.Response
One plain sentence: what was delivered, what was charged, and why fewer came back than asked if that happened.
Why candidates were left out, as reason and count. For example
already_delivered, size_mismatch, size_unknown, country_disputed, credit_cap.Filter values that could not be read, each with
field and value. They are returned, never silently dropped.How a plain word in a filter was read, each with
field, given and read_as. Check it when a word was read as something broader than you meant.Set when the search stopped at one of Agentic ID’s own limits on paid sources. See What it costs.
What it costs
quoted_creditsismax_accountstimes (1 + 2 timesper_account), ormax_creditsif that is lower. Withoutcontact_filtersit ismax_accounts.- When
max_creditsis reached the search stops.fewer_than_askedsays so andexcludedcountscredit_cap. - If your balance covers only part of the request, the part it covers is delivered.
stopped_early values. In every case nothing is charged for what was not delivered.
See Credits for how holds and charges work.
Errors
See Errors for the full list.
Behaviour
- Count first.
count_only: truereturnstotal_at_provider, an emptyaccountsandcontacts, and a cost of 0. Whencount_is_upper_boundistrue, expect fewer on delivery.contact_filtersis not used on a count. keywordsrank,keywords_requiredfilters. By default keywords only order the results: companies that mention more of them come first. Setkeywords_required: trueto make every result mention one. When keywords are the only filter, they always filter.- Words are read, and you are told how. A plain word such as an industry name may be read as a broader category or as a description keyword.
filters_read_asshows it. Check the first results before asking for many. exclude_seenis on by default. Asking again with the same filters returns the next companies: those already delivered to your workspace are skipped and counted inexcludedasalready_delivered.- Fewer than
max_accountsis normal. One call reads a limited number of result pages and drops candidates that fail a check.fewer_than_askedexplains it. Ask again for more, or narrow the filters. - Size needs two sources to be charged. With a size filter, a company whose size is confirmed by only one source is delivered with
size_check: "single"andcharged: false. - People follow the same rules as Find. A person is delivered only with an email that passed verification, and only if the candidate came with a full name or a profile link.
- Long calls. A large search can take minutes. Set your client timeout to match and send an
Idempotency-Key.

