> ## Documentation Index
> Fetch the complete documentation index at: https://dev.jolts.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# How to work with company lists

> Filter, paginate, investigate, and retry without duplicating work.

Use a bearer credential and an active or trialing subscription. API and MCP share the same business
logic and limits. These are supported workflows, not downloadable skill packages.

## Find candidates without returning existing customers

Send this body to `POST /api/companies/search`, or as `search_companies` arguments with a `request_key`:

```json theme={null}
{
  "query": "Companies seeking charging equipment",
  "filters": {
    "countries": ["CA", "US"],
    "kinds": ["procurement_request"],
    "exclude_domains": ["example.com"]
  },
  "limit": 10
}
```

Country filters describe the observation's country, not headquarters or service area. Supported kinds
are `procurement_request` and `facility_expansion`. Demand classes are `explicit_request`, `proxy`,
and `structural`. `occurred_after` and `observed_after` accept ISO 8601 timestamps.

## Restrict a search to known companies

Add `company_ids` or `domains` under `filters`. Exclude using `exclude_company_ids` or
`exclude_domains`. Each accepts up to 100 values. IDs are positive JSON integers; domains must be
hostnames, not URLs or email addresses. Domain matching normalizes case, surrounding whitespace,
and a trailing dot, but does not collapse subdomains or remove `www`.

Values within a field are OR; separate fields are AND. Exclusions win. An empty list does not
restrict. Domain matches require an active, currently evidenced company-domain relationship.
Unknown IDs/domains yield no matches, not invented company records. This is filtering company
evidence search, not a promise to research every supplied company or return one row per input.
Existing bounded acquisition may run for a short first page; the filters remain authoritative over
its results. There is no separate per-input bulk lookup or contact enrichment operation.

## Continue a list

When `next_cursor` is not null, repeat the same query, filters and limit with that cursor and a
**new** request key. At most 100 companies enter the frozen shortlist, with up to three supporting
observations each. Builder permits 25 companies per page; professional permits 50. Pagination
does not acquire more sources, replan, or rerank. Withdrawal can shorten a later page.

## Investigate one company

Call `get_company({"id":123})`, or `GET /api/companies/123`, with an ID returned by search. This
unmetered, subscription-authorized read returns identity, up to three recent deliverable observations,
and domains supported by those observations. It is not a full organization profile. Follow an
observation ID using `get_observation` to inspect its evidence. Neither detail read calls a provider.

## Understand retries and usage

The same account, action, key and normalized inputs refer to one operation, even across API/MCP or
synchronous/background modes. A successful new search settles one request unit and one delivered unit
per distinct company. Fresh-evidence units count newly acquired observations actually delivered.
An identical retry or usage poll adds no charge. Polling another account's usage ID returns not found.

Reads recheck current evidence. If a delivered company loses support, replay can remove it and report
`withheld_units` without changing historical settlement. Raw provider and AI audit details are not
returned. Background operations move `pending` → `processing` → `delivered` or `failed`.

## Verify and troubleshoot

Check `companies`, supporting `evidence`, `coverage`, `usage`, and `request_allowance`, not just the
HTTP status. Similarity is not proof of buying intent. A suppressed or empty result is not proof of
absence. `invalid_cursor` means restart the search without a cursor; `idempotency_conflict` means the
key belongs to different inputs. After a terminal failure use a new key only if you intend new work.
Do not retry invalid inputs unchanged or loop on rate limits.

City/category filters, change feeds, exports, OAuth and whole-dataset downloads are not implemented.
See [MCP tools](/mcp) and the API reference for exact request and response structures.