Discovery
Resolve supplier names and addresses to geographic locations, and discover a company's first-mile supply base โ all without ingesting any assets. The discovery suite is the front door of the "resolve a supplier" flow: turn a name (and optional address) into a usable latitude/longitude, or trace a company back to the production areas and intermediary nodes that supply into it, before any supply-shed, metrics, or compliance work.
โถTwo flows
The suite splits into two sub-groups:
| Group | Endpoints | What it does |
|---|---|---|
| Validate | POST /discovery/validate (+ async poll pair) | Resolve a supplier you already know to a single best-match facility, via a task, or immediately on an exact-cache hit. |
| Source | POST /discovery/source (+ poll pair) | Discover the supply base of a company you don't yet have suppliers for โ potentially dozens of candidates โ asynchronously (dispatch โ poll status โ fetch results). |
โถFacilities and plot boundaries
Discovery resolves facility locations and supply-chain leads. It does not supply verified plot boundaries. A plantation node is not a supplier's plot polygon. Some source candidates have no usable coordinates; do not turn a missing or approximate pin into a plot.
Upload a located facility as location_type: "facility". Obtain plot
boundaries from the supplier or the appropriate ingestion flow.
โถStart with validate
- Validate suppliers whose names you already know. Include their address and country to distinguish companies with the same name.
- Use source when you need a company's suppliers, or when validation has not resolved a credible facility. Review the link evidence, pin status and imagery before carrying a candidate forward.
- For assessed EUDR work, upload the facilities you keep on the EUDR upload fast path.
โถTrace allowance
Each accepted POST /discovery/source call is one Trace, whatever its
depth: a one-tier or direct-operated search, a traversal, or a continuation.
An organization gets 10 Traces, and 30 once it has paid for a checkout. Epoch
can grant more, and some organizations are unlimited. A parent organization
and its child organizations share one allowance. Cached, failed and unspent
runs do not count once settled. POST /discovery/validate spends no Traces.
Read the Traces left on GET /rate-limits/allowances. With none left,
POST /discovery/source returns 402 USAGE_LIMIT_REACHED, unless a repeat
without refresh or continue_from finds an existing cached result.
โถRate limits
These caps apply whatever the allowance. Defaults apply per organization; an organization can have its own limits.
| Request | Default limit | Cache behavior |
|---|---|---|
| Validate | 300 requests/hour | An exact-cache hit returns 200 without spending the limit. |
| Standard one-tier source | 60 dispatches/hour | Charged at dispatch, even when the result comes from cache. |
| Direct-operated source | Separate 120 dispatches/hour pool | Charged at dispatch, even when the result comes from cache. |
| Traversal | 80 sweeps/day (the daily trace-sweep limit) | Full max_sweeps charged at dispatch; unused sweeps refunded when settled. |
A 429 response carries Retry-After, and data.details names the limit,
the counts and resets_at. Reduce a max_sweeps that exceeds the whole
daily limit. GET /rate-limits reports each limit before it is hit.
See the Validate and Source sub-folders for the endpoint pages.
Required scope:
geocode:read. Dispatching a source discovery and recording a decision on it also needdiscovery:write.