# Innerfetch API

> B2B data enrichment API built from the public web: company details, customers, partners, vendors,
> competitors and people for a given company domain, each relationship with the public page that shows it.

Authentication: send `X-API-Key: gtm_live_…` (or `Authorization: Bearer gtm_live_…`).
Every metered response carries `X-Credits-Cost` (credits charged for this call) and `X-Credits-Remaining`.
Errors are RFC 9457 problem+json. You are never charged for errors, 202s, 404s or 503s, with one exception: `404 company_not_found` from `/company/details` costs 1 credit.
Responses use snake_case JSON. `domain` accepts a bare domain, a URL, or an email address.
A company's old domain (one it moved away from) answers with the company under its current domain, at the same price.

Freshness: company endpoints always answer from stored data at once (typically < 50 ms) and refresh data
older than 30 days in the background; `fresh=true` queues that refresh now. `cache=only` reads stored data,
also when stale, and never queues anything: a company not in the graph is a free `404` with code `not_in_graph`,
and `cache=only` together with `fresh=true` is `400 conflicting_parameters`. A company never seen before is
crawled while you wait (typically 5–20 s) and returns partial data; if that takes longer you get `202` with
`Retry-After` and nothing is charged. `X-Enrichment-Status` says what you got: `complete`, `partial` (some
fields are still being filled: industry, business model and similar companies may be missing), `refreshing`,
`refresh_deferred` (stored data; your organization already has 50 refreshes waiting, so none was queued and
`fresh=true` adds no credit) or `queued`. A `fresh=true` details call for a company whose refresh is already
queued costs the normal price.
Poll the free `/company/status` endpoint until it says `complete` instead of polling a paid endpoint.
Or add `callback_url=https://…` to details, customers or competitors: once the company is `complete` (or
`not_found`) we POST a Standard Webhooks message (`webhook-id`, `webhook-timestamp`, `webhook-signature`;
body `{"type":"company.enrichment.completed","timestamp":…,"data":{"domain":…,"status":…}}`) signed with the
secret from `/callbacks/secret`. Free; retried up to 6 times over about 9 hours; dropped after 24 h without
`complete`; no redirects followed; at most 100 pending per organization (more is a free `429 callback_limit`).
An organization may have at most 10 never-seen companies waiting for their first data (200 from
`/company/batch`, which wait behind all other work); another one is answered `429` with `Retry-After` (free).
Companies already in the graph, or already queued, never count. A domain whose crawl found no website
answers `404` for a day (1 credit on `/company/details`, free elsewhere), then is crawled again. Queued work is shared out between organizations in turn.
Trial organizations (made by a console sign-up, no payment yet) have lower limits until their first payment:
60 requests a minute per key, 3 never-seen companies waiting at once (3 from batches),
25 new never-seen companies a UTC day and 2 active keys. Over a limit the answer is the usual free `429`
(`rate_limited` or `queue_full`) and its `detail` names the trial limit. A sign-up with a verified work e-mail
gets 200 trial credits for 30 days, once per e-mail domain.

## Endpoints

- [Company details](https://api.innerfetch.com/api/v1/company/details?domain=stripe.com): firmographics, technographics (tech stack, email provider/gateway, email pattern), open roles by department, `tagline`, `cover_image_url` and `social_profiles` (LinkedIn, X, Facebook, Instagram, YouTube, GitHub, TikTok), `company_type` (public, private, nonprofit, government, educational or unknown), `public_listing` (stock ticker and exchange), `sic_code` and `identifiers` (LEI, SEC CIK, ISIN, when known), and `executives` (up to 20 people with an executive role found on the public web, at no extra cost). 2 credits (+1 with `fresh=true`); 1 credit for `404 company_not_found` (no public web presence found, also on a repeat within the day); 0 for `404 not_in_graph` with `cache=only`.
- [Company customers](https://api.innerfetch.com/api/v1/company/customers?domain=stripe.com&max_results=20): customers with confidence scores and verbatim evidence quotes. Only customers with a verified domain are returned; `include_unverified=true` adds guessed and rejected ones (see `domain_status`). `include=partners` (or `include=customers,partners`) adds `partners`: partner platforms, integrations and marketplace listings found on the public web (investors are not offered). `fresh=true` queues a refresh. Up to 200 per page and list (`max_results`); pass `next_cursor` (customers) or `partners_next_cursor` (partners) back as `cursor` with that one list in `include` (null on the last page). 1 credit + 2 per row returned over all lists, per page.
- [Company vendors](https://api.innerfetch.com/api/v1/company/vendors?domain=openai.com&max_results=20): the reverse of customers: vendors with a public page that names the company as their customer, and vendors the company itself names on the public web, each with that evidence page (and quote when there is one) and its `card`. Rows only when the company's own domain is verified (`company_domain_status`); otherwise the list is empty and free, unless `include_unverified=true`. Answers from stored data only: never crawls, and an unknown company is a free `404 not_in_graph`. Up to 200 per page with `cursor` / `next_cursor`. 1 credit + 2 per vendor returned, per page.
- [Company people](https://api.innerfetch.com/api/v1/company/people?domain=linear.app&limit=25): people of the company found on the public web, with the published `title`, `roles` (`ceo`, `cto`, `cfo`, `coo`, `cmo`, `cro`, `cpo`, `ciso`, `founder`, `co_founder`, `president`, `chair`, `other`), `seniority` (`c_suite`, `vp`, `director`, `manager`, `ic`) the page where each was seen (`evidence.url`) and `linkedin` (the person's LinkedIn profile when known, else null). Executives first, then by name. People the company lists as investors, advisors or board members come last, with `affiliation` (`investor`, `advisor` or `board`; null for staff), no `roles` and no `seniority`, and are never in `executives`. Only the people from the latest check are shown; a person known only from their own profile page stays for 12 months after it was last read. Filters `seniority`, `role` and `title` (part of the title, no case). No e-mail: use the work email lookup. A never-seen company behaves as in details (`202` queued); `cache=only` and `fresh=true` as in details. Up to 100 per page (`limit`, default 25) with `cursor` / `next_cursor`. 1 credit + 1 per person returned; an empty list costs 1, or 0 while `partial`.
- [Company competitors](https://api.innerfetch.com/api/v1/company/competitors?domain=stripe.com&limit=10): evidenced competitors first, then similar companies in the same market that are not confirmed competitors (`basis`: `evidenced` | `similar`). Each row has a `reason` (`compare_page`, `compare_page_text`, `similar_profile`); a similar row's `confidence` is how often such rows are real competitors, with its `similarity` and `match_score` beside it. `fresh=true` queues a refresh at no extra cost. 3 credits; 0 for an empty list while `partial`.
- [Company batch](https://api.innerfetch.com/api/v1/company/batch): POST `{"domains":["stripe.com","linear.app"],"cache":"only"}` (1–50 entries; `cache` optional). One result per input with `status` `found` (with `data`), `queued`, `queue_full` (200 never-seen companies from batches already waiting), `not_found` (with `cache=only`, or when the last crawl found no website) or `invalid` (with `error.code`). Never crawls while you wait. 2 credits per distinct found domain; the balance must cover 2 per distinct valid domain first. Own rate limit: 30 batches per minute per key.
- [Company search](https://api.innerfetch.com/api/v1/company/search?q=tools%20to%20chase%20unpaid%20invoices&max_results=10): enriched companies ranked by the meaning of a plain-words query (`q`, 3–200 characters; `max_results` 1–50, default 10). Each row has `domain`, `name`, `similarity`, `match_score` and the company `card`. Only strong matches are shown, so an answer can be shorter than `max_results` or empty. Never crawls. 1 credit per started 50 rows; an empty answer is free. Own rate limit: 60 searches per minute per key; `503 busy` with `Retry-After` when search is busy (free).
- [Company status](https://api.innerfetch.com/api/v1/company/status?domain=stripe.com): `complete`, `partial`, `refreshing`, `queued` or `not_found`, with `last_enriched_at` and `fields_completed_at`. Never starts a crawl. Free.
- [Public profile](https://api.innerfetch.com/api/v1/profile?url=https://example.com/team/jane-doe): the person described by an openly published page. Pages that need a sign-in are rejected. 2 credits (+1 with `fresh=true`); 0 if no person is found.
- [Work email lookup](https://api.innerfetch.com/api/v1/work-email/lookup): POST `{"first_name":"Jane","last_name":"Doe","domain":"example.com"}`. Billed by verdict: `valid` 2, `likely_valid_pattern` / `catch_all_domain` 1, `unknown` / `invalid` 0. No e-mail is sent.
- [Callback secret](https://api.innerfetch.com/api/v1/callbacks/secret): the `whsec_` secret that signs your callbacks; POST `/api/v1/callbacks/secret/rotate` replaces it at once. Free.
- [Credit balance](https://api.innerfetch.com/api/v1/credits): the balance with `plan_credits` (spent first), `payg_credits` and their expiry dates. Free.
- [Usage](https://api.innerfetch.com/api/v1/usage?from=2026-10-01&to=2026-10-31): per UTC day and endpoint, requests by status class and the credits charged (at most 92 days; last 30 by default). Free.
- [Billing plans](https://api.innerfetch.com/api/v1/billing/plans): free.
- [Pricing](https://api.innerfetch.com/api/v1/pricing): plans and packs with list prices (minor units), the credits of every endpoint and the free trial with its limits, as JSON. No key needed. Free.
- [Checkout](https://api.innerfetch.com/api/v1/billing/checkout): POST `{"plan":"pack_10k"}` → hosted checkout URL. One subscription per workspace: a second one is `409 subscription_exists` (change the plan in the console). Free.

People data: only names, titles and links published on the public web, never from a page behind a sign-in; no
guessed e-mail addresses in lists. Removal: e-mail support@innerfetch.com with the page URL, or
the full name and the company domain. The person is deleted and kept out of later answers, including
`/profile`.

Every customer, partner, vendor and competitor row carries a `card` (description, industry, logo URL, HQ country, employee range,
`enriched`, `tagline`, `linkedin`, `x`), so a list needs no second call. `enriched=false` means the counterparty has no profile of
its own yet, and its card fields are empty. Company details list every known `websites` entry, primary first.

## MCP

- [MCP server](https://api.innerfetch.com/mcp): stateless Streamable HTTP, same key (`X-API-Key` or `Authorization: Bearer`), same prices, rate limit and error codes as REST. Tools: `company_details`, `company_customers`, `company_competitors`, `company_status`, `company_batch`, `company_search`, `company_vendors`, `company_people`, `profile_lookup`, `work_email_lookup`, `credits_balance`, `usage`. Each result is JSON with `data`, `credits_charged`, `credits_remaining` and `trace_id`; an error result has `code`. `GET /mcp/health` is free and needs no key.

## Pay per call without an account (x402)

An agent without an API key can pay for each call in USDC on Base with x402 (version 2, scheme `exact`).
Send the request without a key. A payable endpoint answers `402 payment_required` with a quote in the `PAYMENT-REQUIRED` header
(base64 JSON; `accepts[0]` has `amount` in millionths of a USDC, `asset`, `payTo` and `network`). Sign it and send the same request
again with the signed payment in `PAYMENT-SIGNATURE`. A billable answer costs the full quote, at 0.0145 USDC a credit:
`/company/details` is 0.029 USDC. A list is quoted and charged for a full page of `max_results` or `limit` rows, so ask only for the rows you need.
The payment is taken only when the answer costs credits: a `202`, an empty `partial` list, an error or another free answer takes nothing.
Each signed payment is good for one call: sign a new one for every request, valid for at least 60 seconds
and at most `maxTimeoutSeconds`, for exactly `amount` to `payTo`. A paid answer carries `PAYMENT-RESPONSE` (base64 JSON with the `transaction`).
A billable answer is sent only after the payment is confirmed; when it cannot be confirmed in time the answer is `503` and the same payment must not be sent again.
Limits without a key: 60 requests a minute per client address (`429` above it, nothing charged),
3 never-seen companies waiting at once and 50 new ones a UTC day, shared by all keyless callers,
and 20 free answers a UTC day per paying wallet and per client address (then `402 free_answer_limit`).
A wallet or client address whose payment fails after the check because the funds moved or the payment was canceled is refused for 24 hours (`402 payer_blocked`).
Payable: company details, customers, vendors, people, competitors and search, public profile and work e-mail lookup. Batch, MCP, `callback_url`
and the account endpoints need an API key. `GET /api/v1/pricing` has the terms in `pay_per_call`, and `/openapi.json` lists the payable endpoints
with the USD price range of each in `x-payment-info`. Codes: `payment_required`,
`payment_invalid` (the body's `reason` says why, for example `payment_already_used`) and `payment_failed`.

## Docs

- [Full reference: prices, MCP tools, every endpoint with an example answer](https://api.innerfetch.com/llms-full.txt)
- [Agent skill (SKILL.md; its version changes with its content)](https://api.innerfetch.com/skills/innerfetch/SKILL.md)
- [OpenAPI document](https://api.innerfetch.com/openapi/v1.json)
- [Interactive reference](https://api.innerfetch.com/docs)

## Status codes

- 400 invalid input · 401 missing/invalid key · 402 insufficient credits (a list or batch that the balance pays only in part is cut instead: see Prices), or pay per call without a key · 404 not found (free, except `company_not_found` from `/company/details`: 1 credit) · 202 queued for enrichment (free; retry after `Retry-After`) · 429 rate limited or too many new companies queued (free; honour `Retry-After`) · 503 at capacity (free; honour `Retry-After`)

## Error codes and headers

Every error body has a stable `code` (schema `ErrorCode` in the OpenAPI document) and a `trace_id`. Branch on `code`, not on `title`.
Codes: `invalid_request`, `invalid_domain`, `invalid_url`, `conflicting_parameters`, `batch_too_large`, `invalid_api_key`, `invalid_signature`, `insufficient_credits`, `payment_required`, `payment_invalid`, `payment_failed`, `organization_suspended`, `not_found`, `company_not_found`, `profile_not_found`, `not_in_graph`, `payload_too_large`, `rate_limited`, `queue_full`, `callback_limit`, `callbacks_disabled`, `subscription_exists`, `internal_error`, `upstream_error`, `busy`. A `402 insufficient_credits` body also has `required_credits`. `403 organization_suspended` means the organization's API access is suspended (for example during a payment dispute); contact support@innerfetch.com.

Every authenticated response carries `X-RateLimit-Limit` (requests per minute you can make now, the lower of your key's
and your address's limits), `X-RateLimit-Remaining` (requests left now) and `X-RateLimit-Reset` (seconds until both are
full again), plus the credit headers.
Company answers (200) carry `X-Data-Age-Days` (whole days since the data was last collected) and `Last-Modified`.