---
name: innerfetch
description: Look up B2B companies with the Innerfetch API or its MCP server - firmographics, technographics, open roles, publicly evidenced customers, partner platforms, vendors, competitors and similar companies, company search by meaning, the people and executives of a company, public profiles and work e-mail. Use when a task needs facts about a company from its domain, its customers, vendors or competitors, companies that match a description, or enrichment of a list of domains.
---

# Innerfetch API

Innerfetch API answers B2B company questions from data built from the public web. Calls are billed in credits.

Skill version `d1fb90e95e67`. Get the current copy from https://api.innerfetch.com/skills/innerfetch/SKILL.md. Get it again when an answer has a field, tool or error code that this file does not name, and at least once a week; replace your copy when the version differs.

## Setup

- Key: the environment variable `INNERFETCH_API_KEY`. Send it as `X-API-Key: <key>` or `Authorization: Bearer <key>`. Never print it.
- REST base URL: `https://api.innerfetch.com/api/v1`. MCP: `https://api.innerfetch.com/mcp` (stateless Streamable HTTP, same key).
- Full reference with example answers: `https://api.innerfetch.com/llms-full.txt`. OpenAPI: `https://api.innerfetch.com/openapi/v1.json`.

## MCP tools

- `company_details`: Company profile: firmographics, technographics, hiring. Never-seen companies are crawled (partial data, or queued). Costs 2 credits (+1 with fresh=true when it queues a refresh); 1 when no company is found; 0 when queued or, with cache=only, not stored.
- `company_customers`: Customers publicly evidenced for the company, verified domains only unless includeUnverified, with evidence quotes; include=partners adds partner platforms. Pages of up to 200 per list; pass next_cursor or partners_next_cursor back as cursor. Costs 1 credit + 2 per row returned over all lists; 0 when queued.
- `company_vendors`: Vendors of the company: vendors with a public page that names it as their customer, and vendors it names itself on the public web, with that evidence page (and quote when there is one). Rows only when the company's domain is verified unless includeUnverified (an empty list held back for that reason is free). Answers from stored data only; an unknown company is not_in_graph at no cost. Pages of up to 200. Costs 1 credit + 2 per vendor returned.
- `company_people`: People of the company found on the public web, with the published title, executive roles (ceo, cto, founder, …), seniority and the page where each was seen; executives first; investors, advisors and board members last, with affiliation and no roles. Filter by seniority, role or title. No e-mail: use work_email_lookup. Pages of up to 100. Costs 1 credit + 1 per person returned; 0 when queued or for an empty partial list.
- `company_competitors`: Competitors: evidenced competitors first, then similar companies (basis similar, same market, not confirmed competitors). Costs 3 credits; 0 when queued or for an empty partial list.
- `company_status`: Enrichment status of a company (complete, partial, refreshing, queued, not_found) without starting a crawl. Free.
- `company_batch`: Company details for up to 50 domains in one call, one result per input (found, queued, queue_full, not_found, invalid). Never crawls while you wait. Costs 2 credits per distinct found domain.
- `company_search`: Finds enriched companies by what they do, from a plain-words query; rows have the company card and similarity and match_score, and an answer may be empty. Never crawls. Costs 1 credit per started 50 rows; 0 when empty.
- `profile_lookup`: The person described by an openly published page (bio, speaker page). Pages that need a sign-in are rejected. Costs 2 credits (+1 with fresh=true); 0 when no person is found.
- `work_email_lookup`: Finds and checks a work e-mail; no e-mail is sent. Billed by verdict: valid 2 credits, likely_valid_pattern or catch_all_domain 1, unknown or invalid 0.
- `credits_balance`: The credit balance, split into plan and pay-as-you-go credits with their expiry dates. Free.
- `usage`: Requests by status class and credits charged, per UTC day and operation, over at most 92 days. Free.

## Prices

Errors, `202`, `404`, `429` and `503` answers cost no credits, except `404 company_not_found` from `/company/details`, which costs 1. A call is refused with `402` before any work when the balance is below its maximum price; a list (customers, vendors, people) is refused only below the price of one row per list, and is cut to what the balance pays, with `notice` and the next cursor. A batch then answers `insufficient_credits` for found entries past what the balance pays.

| Endpoint | Credits | Free when |
| --- | --- | --- |
| `GET /api/v1/company/details` | 2 (+1 with `fresh=true` when it queues a refresh); 1 for `404 company_not_found` | `202` queued, `404 not_in_graph` with `cache=only` |
| `GET /api/v1/company/customers` | 1 + 2 per row returned over all lists (`include=customers,partners`), at most 401 a page per list | `202` queued |
| `GET /api/v1/company/vendors` | 1 + 2 per vendor returned, at most 401 a page | `404 not_in_graph`, an empty list held back because the company's domain is not verified |
| `GET /api/v1/company/people` | 1 + 1 per person returned, at most 101 a page; executives in details are free | `202` queued, an empty list while `partial` |
| `GET /api/v1/company/competitors` | 3 | `202` queued, an empty list while `partial` |
| `POST /api/v1/company/batch` | 2 per distinct found domain (up to 50 entries) | `queued`, `queue_full`, `not_found`, `invalid` and duplicate entries |
| `GET /api/v1/company/search` | 1 per started 50 rows returned | an empty answer |
| `GET /api/v1/company/status` | 0 | |
| `GET /api/v1/profile` | 2 (+1 with `fresh=true`) | no person found |
| `POST /api/v1/work-email/lookup` | `valid` 2, `likely_valid_pattern` or `catch_all_domain` 1, `unknown` or `invalid` 0 | |
| `GET /api/v1/credits`, `GET /api/v1/usage`, `GET /api/v1/pricing`, `GET /api/v1/billing/plans`, `POST /api/v1/billing/checkout` | 0 | |
| `POST /mcp` (each tool) | the price of the endpoint the tool calls | the same cases |

## 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`.

## Rules

1. Use `company_batch` for a list of domains, not a loop of `company_details`. A batch never crawls while you wait and charges only found domains.
2. Use `cache=only` for a cheap check: it reads stored data, never starts a crawl, and an unknown company is a free `not_in_graph`. Do not send it together with `fresh=true`.
3. `company_details` without `cache=only` costs 1 credit when no company is found (`company_not_found`). Do not send it guessed domains; check them with `cache=only` or a batch first.
4. A never-seen company is crawled in the background. On `202` or `enrichment_status: queued`, poll the free `company_status` until it is `complete`, with the `Retry-After` delay. Do not repeat a paid call to wait.
5. `partial` means some fields are still being filled: industry, business model and similar companies can be missing.
6. `company_search` finds enriched companies by the meaning of plain words. It never crawls, so a company we have no data for is not found. It can return fewer rows than asked, or none (free).
7. On `/company/customers`, only verified customer domains come back by default. Add `include=partners` for partner platforms (integrations and marketplace listings); every row of every list costs the same, so ask only for the lists you need. Investors are not offered. For more than one page, pass `next_cursor` (customers) or `partners_next_cursor` (partners) back as `cursor`, with only that list in `include` and the same other parameters.
8. Use `company_vendors` to answer "which vendors does this company use": vendors that name it as a customer, and vendors it names itself. It answers from stored data only, so it never crawls; an unknown company is a free `not_in_graph`. When `company_domain_status` is not `verified`, the list is empty and free; send `include_unverified` only when the user accepts guessed matches.
9. Use `company_people` for the people of a company found on the public web; filter with `role` (e.g. `ceo`) or `seniority` (e.g. `c_suite`) so you pay only for the rows you need. For executives alone, `company_details` already has `executives` at no extra cost. A list has no e-mail; call `work_email_lookup` only for the person you need. `linkedin` is set only when known; never guess one. Never present a title as current beyond its `last_verified_at`. A row with `affiliation` (`investor`, `advisor`, `board`) is not staff: never present it as an employee.
10. A competitor row with `basis: "similar"` is a company in the same market, not a confirmed competitor. Say so when you report it. Its `confidence` is how often such rows are real competitors.
11. Branch on the error `code`, never on the message. `402 insufficient_credits` has `required_credits`. A list that the balance pays only in part comes back cut, with `notice` and the next cursor: top up, then pass the cursor. A batch entry past it has `status` `insufficient_credits`. `403 organization_suspended` stops every call of the organization (for example during a payment dispute): stop and tell the user to contact support@innerfetch.com. `429` and `503` are free; wait for `Retry-After`.
12. Run independent read-only calls in parallel. Stay under the key's rate limit (`X-RateLimit-Remaining`). A trial organization (console sign-up, no payment yet) has 60 requests a minute per key, 3 never-seen companies waiting at once and 25 new ones a UTC day; on `queue_full`, poll `company_status` for the waiting ones instead of adding more.
13. Customer, vendor and evidenced competitor rows carry `evidence` (a page and a quote). Quote it when the user must trust a claim.
14. To buy credits, `POST /api/v1/billing/checkout` returns a hosted checkout URL for the user to open; credits arrive only after the payment. A workspace holds one subscription: a second subscription checkout is `409 subscription_exists`, and the owner changes the plan in the console instead (an upgrade at once with a new cycle and the new plan's full credits, a downgrade at the next billing date). Packs can be bought at any time. `GET /api/v1/pricing` lists the plans with their `rank` (higher is bigger).

Error 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`.