How the /v1/find endpoint works

The dataset endpoints answer in the same request. POST /v1/find is the other mode: you describe the list you want in plain English, an agent works it across the datasets and the live web, and the finished list arrives by email and stays available over the API. It is asynchronous and can take up to 24 hours, because when the answer is not already in the graph the agent scrapes it fresh.

The request

curl -X POST https://api.tamgraph.com/v1/find \
  -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"query": "B2B SaaS companies doing $1-10M ARR that
        sponsor newsletters", "limit": 500}'

query is required and runs 10 to 2000 characters. notify_email is optional and defaults to your account email. limit is optional, 1 to 5000 — omit it and you get every matching company up to the row cap. Put the count in limit, not in the prose: the text says who you want, the parameter says how many.

The response is {"job_id", "status": "queued", "eta", "notify_email"}.

Polling and collecting

• GET /v1/find/{job_id} — status of a job you submitted. Once it is done the response also carries result_count, summary and csv_url. Jobs belonging to another key return 404.
• GET /v1/find/{job_id}/csv — the finished list as one CSV download.
• GET /v1/find/{job_id}/results?limit=100&cursor= — the same list as JSON. Pass next_cursor back as cursor until it comes back null.

Asking before the job is finished returns 409 with the current status. Lists finished before row-level storage existed also return 409 from /results — download those from /csv.

Asking for people

Describe people rather than companies — "CMOs at US SaaS companies between $1M and $10M ARR", "founders of Shopify agencies in the UK" — and the agent builds the company list first, then finds the people at those companies. Each contact row has full_name, title, company and an email with an email_status column: verified_source for an address from verified data, pattern_guess or reported_format_guess for one built from the domain's naming pattern, and none when there is no address. A guess is always labelled as a guess.

Lookalikes

A domain works as a description too. "Companies similar to coinbase.com", or "lookalikes of these 20 customers" followed by the domains, runs a vector-similarity search over company embeddings and returns the nearest matches, ranked.

Daily limits

Every agent search runs an agent, so they are capped per day: 3 a day on the trial, 25 a day on Pro. Over the cap the endpoint returns 429 and the count resets the next day. The rate limit is 5 requests a second on both plans.