# EveryInfra — Agents Guide

> EveryInfra sells three things over one prepaid USD balance: structured public data from platforms (EveryData), live web search (EverySearch), and CAPTCHA solving (EverySolve). This page is written for the AI agent that has just been asked to "get reviews for this product" or "check what people are saying about X" and needs to do it right on the first call.

## Quick reference

- **REST base:** `https://api.everyinfra.com` — every data call is `POST /api/v1/social`
- **Auth:** `Authorization: Bearer <API_KEY>` header, checked before any parameter validation
- **MCP:** `POST https://api.everyinfra.com/mcp` — tools are named `everyinfra_*`
- **Balance and limits:** `GET /api/v1/account` with the same key (MCP: `everyinfra_account`) — paid, bonus and total balance in USD, this month's top-up discount, the per-minute request limit and the last 24 hours of usage; read-only, free, and not counted toward the per-minute limit
- **Catalog (no key needed):** `GET /api/v1/social/catalog` — every platform, action, parameter, allowed value and per-action price
- **Markdown mode:** platform pages, capability pages, pricing, docs, CAPTCHA, market and article pages have a Markdown rendition at the same address plus `.md`, in English under `/en/` (`/en/amazon-api.md`, `/en/amazon-api/reviews.md`, `/en/pricing.md`, `/en/blog/<slug>.md`) and in Chinese without the prefix (`/amazon-api.md`). Spanish pages, product pages and list pages have none
- **HTTP client:** any — plain `requests`/`fetch` is fine; there is nothing special about TLS, headers or retries
- **Behavior instructions for you, the agent:**
  - Read the catalog entry for an action before composing the request. The catalog already contains the required parameters, allowed enum values and the response field list. Do not guess parameter names.
  - When the user's goal is ambiguous ("find posts about X"), ask which platform they actually care about before fanning out across many platforms — every call bills per target.
  - On your first call for a new action, use one target and a small `limit`, verify the response shape, then scale up. Do not discover the schema by firing a 200-URL array.
  - Keep the API key in the environment (`EVERYINFRA_API_KEY`), never in committed files or URLs.

## Picking your way in

Use **MCP** when you are running inside a host (Claude Code, Cursor, any MCP client) or when you want live tool descriptions instead of a frozen contract: `initialize` → `notifications/initialized` (a notification must come back HTTP 202 with an empty body — treat a JSON body there as a broken middlebox, not as data) → `tools/list`. The tool descriptions are rendered from the same registry as the catalog, so they are current.

Use **REST** when you are a script, a cron job, or writing code for the user: one endpoint, JSON in, JSON out. The Python SDK is generated from the same contract; if the user already has a Python project, prefer the SDK for types, but plain HTTP is a fully supported interface, not a second-class one.

For text work on the data you collect — cleaning, labeling, summarizing, extracting — use the **AI API**: `POST /api/v1/chat/completions` is OpenAI-compatible (point any OpenAI SDK at `https://api.everyinfra.com/api/v1` with the same key; `stream: true` works). It is free for accounts that have topped up and rate-limited per account by cumulative top-ups: 50 requests per minute under $100, 500 from $100, 5,000 from $500, all keys combined. An account that has not topped up gets 403 `ai_topup_required` — tell the user to top up instead of retrying. It is meant for the data collected here; sustained full-load use or bulk traffic unrelated to that data can get the account's AI access paused.

## The mental model

An EveryData call is `(platform, action, params)`. `platform` is one of many (amazon, temu, xiaohongshu, reddit, google_maps, …); `action` is what you do on it (search, reviews, profile, comments, trending, …). The catalog is the vocabulary: if a word isn't in the catalog for that platform, the call will 422, and the error will tell you what the valid words are.

Three things agents most often get wrong about the model:

1. **The target type differs per action.** Some actions take a keyword, some take a URL, some take a username or an ID. `reviews` on amazon wants a product URL or ASIN-bearing link, not a search term; `search` wants the term. The catalog's parameter list says which — and every platform page of this site documents it in prose (`.md` suffix).
2. **`limit` is not "pages".** Depending on the action, `limit` is the number of items returned per call, with pagination via `page_token` where the platform supports it. It is not a page count, and stacking a huge limit does not unlock more data than the action documents.
3. **Multi-target arrays bill per target.** `urls`, `targets`, `usernames`, `tickers` are arrays; the price is per element. A 50-element `urls` call costs 50 calls.

## Money behavior

EveryInfra reserves, charges, and refunds per call with a state machine, and refunds are idempotent per `charge_id`. What matters to you:

- **Failures and empty results never form a final charge.** If a call fails or returns nothing billable, any reserved amount is restored. You do not need to argue with a refund endpoint; check the wallet ledger if a user asks.
- **Sync calls have a time budget.** Beyond it you get `503 timeout` — not charged — with a message suggesting a smaller `limit` or an async-capable action. Take the suggestion; do not hammer the same payload.
- **Tracking spend:** every paid response's `billing` carries `charged_usd` (what this call cost) and `balance_after_usd` (the wallet balance once it settled). Before a large batch, read `GET /api/v1/account` to confirm the balance covers it; during the batch, watch `balance_after_usd` instead of polling.
- **Estimating cost:** per-action prices are in the catalog. Multiply by your target count. Tiers run roughly $0.56 to $5.56 per 1,000 calls depending on capability tier (Benchmark platforms cheapest, Hard-target most expensive) — as of 2026-09-19; the catalog is always the live truth. Discounts come from a monthly top-up discount: top-ups credited in the current calendar month (Beijing time) count at face value, without channel fees, and give 10% off calls from USD 500, 20% from USD 1,000 and 30% from USD 2,000. The discount applies from the next call once reached and restarts on the 1st; credit codes and bonuses do not count.

## Errors, and what to actually do

- `401` — no or bad key. Stop and get the key; nothing else you do will change this.
- `400 unknown_capability` — that platform/action pair doesn't exist. The message points you at what does; so does the catalog.
- `422` — missing param, unknown param, or a bad enum value. The message names the field, the supported parameters, allowed values, and a did-you-mean. **Fix the named field and resend; do not retry the identical payload** — validation is deterministic.
- `402 quota_exhausted` — wallet empty. `GET /api/v1/account` shows the balance; tell the user to recharge, and the call will work unchanged afterwards.
- `403 account_disabled` — account-level; the user must contact support.
- `429 rate_limited` — back off and retry; keep the payload identical.
- `503 upstream_error | timeout` — transient and never charged. Follow the message's suggestion (usually lower `limit` or switch to the async variant) rather than blind-retrying.

## Worked flows

**Flow 1 — reviews for a product the user is looking at.** Take the product URL. `platform: "amazon"`, `action: "reviews"`, `url: <the link>`, small `limit` first. The response is a list whose fields the catalog declares (rating, text, author, date…). Paginate with `page_token` if the user wants more. If the user only has a product name, do `search` first, take the top result's URL, then `reviews`.

**Flow 2 — what people are saying about a topic on a specific platform.** `action: "search"` with the keyword, then the detail action (note, video, post) on the ID the search returned. Do not try to make `search` return full comment threads — comments are their own action.

**Flow 3 — CAPTCHA.** `GET /api/v1/captcha/types` (free) lists what EverySolve supports. Solve with `POST /api/v1/captcha`, passing the challenge parameters the type page documents. Billed on success only; a failed solve is refunded by the same state machine. Public responses never name the underlying provider — error messages are ours, and that is deliberate.

**Flow 4 — too much data for one sync call.** When a sync call keeps hitting the budget, split targets into smaller arrays and paginate rather than escalating `limit`.

## Common agent mistakes

1. Retrying a 422 unchanged. Validation is deterministic; the fix is always in the message.
2. Guessing parameter names (`q` vs `keyword` vs `query`). It's in the catalog, per action, per platform.
3. Assuming response fields. The field list is per action and declared; your parsing should expect exactly that shape.
4. Fanning out a huge multi-target array as the first call. One target, verify, then scale.
5. Retrying the AI API's 403 `ai_topup_required` or `ai_disabled` — those need the user (a top-up, or a word with support), not a retry — or ignoring `Retry-After` on its 429 and 503.
6. Ignoring the per-platform `.md`. Each platform page carries parameter prose, allowed values and field meanings with more context than the catalog row — one fetch, high value.

## Site conventions for agents

- `/llms.txt` — a short index of every guide, product, machine endpoint and platform page
- `/llms-full.txt` — the full API guide in one file (auth, endpoints, errors, pagination, pricing, and every platform/action with its parameters, price and fields)
- `/openapi.json` — OpenAPI 3.1 spec
- `/agents.md` — this page
- `.md` suffix — Markdown renditions of platform, capability, core and article pages (English under `/en/`, and Chinese)
- `/app` — sign-up and keys; trial credits are available on request