# POST /entities: $0.005 per call

Named-entity extraction: the organisations, people, places, products, events, dates, amounts of money and laws in a text or document (URL to a page or PDF), with how often each is mentioned. Every entity is checked by code to really appear in the source, so nothing is made up. Filter with types. About 12,000 characters read per call.

- **Price:** $0.005 in USDC, the same on Base, Solana, Polygon, Arbitrum. Failed calls are never charged.
- **Free trial:** yes, 20 free calls a day from Claude, Cursor or any MCP client ([set-up](/mcp/setup)).
- **Tier:** live
- **Answers cached for:** 1 day(s)
- **Data sources:** our /markdown reader (PDF, Word, web pages); Workers AI: Llama 3.1 8B (metered)
- **Lane:** AI tools ([OpenAPI](/openapi/ai.json))
- **Live health:** [status page](/status)

## Free sample

See an answer for the demo input first, free (no payment, 10 a minute): [https://aayatai.com/sample/entities](/sample/entities). It is a stored real answer when we have one, otherwise an example marked `"kind": "illustrative"`.

```bash
curl "https://aayatai.com/sample/entities"
```

## 1. See the price (free)

Call it without paying: you get `402 Payment Required` and a `PAYMENT-REQUIRED` header with the exact price and where to pay.

```bash
curl -i -X POST https://aayatai.com/entities -H "content-type: application/json" -d '{"text":"Cloudflare, based in San Francisco, launched Workers AI in September 2023; Microsoft invested $10 billion in OpenAI."}'
```

## 2. Pay and call (TypeScript)

```bash
npm install @x402/fetch @x402/evm viem
```

```ts
import { wrapFetchWithPaymentFromConfig } from "@x402/fetch";
import { ExactEvmScheme } from "@x402/evm";
import { privateKeyToAccount } from "viem/accounts";

// A wallet used only by your agent, holding a little USDC on Base.
const account = privateKeyToAccount(process.env.WALLET_PRIVATE_KEY as `0x${string}`);
const pay = wrapFetchWithPaymentFromConfig(fetch, {
  schemes: [{ network: "eip155:8453", client: new ExactEvmScheme(account) }],
});

const res = await pay("https://aayatai.com/entities", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({"text":"Cloudflare, based in San Francisco, launched Workers AI in September 2023; Microsoft invested $10 billion in OpenAI."}),
});
console.log(await res.json());
```

## 3. Or as an MCP tool

```ts
// MCP server: https://aayatai.com/mcp (Streamable HTTP). With the x402 MCP client (see /start):
const result = await client.callTool("entities", {"text":"Cloudflare, based in San Francisco, launched Workers AI in September 2023; Microsoft invested $10 billion in OpenAI."});
```

## Inputs

- `text` (string): The text to read (use this or url).
- `url` (string): A web page or document to read (use this or text).
- `types` (array): Only these kinds (default: all): organisation, person, place, product, event, date, money, law, work, other.

Bad inputs are rejected with HTTP 400 before any payment is asked for.

## Example answer

Example only: the shape of an answer, with placeholder addresses and made-up figures. It is not data about any real token or wallet; call the service (or its free sample) for real results.

```json
{
  "entities": [
    {
      "text": "Cloudflare",
      "type": "organisation",
      "count": 1
    },
    {
      "text": "Microsoft",
      "type": "organisation",
      "count": 1
    },
    {
      "text": "OpenAI",
      "type": "organisation",
      "count": 1
    },
    {
      "text": "San Francisco",
      "type": "place",
      "count": 1
    },
    {
      "text": "Workers AI",
      "type": "product",
      "count": 1
    },
    {
      "text": "September 2023",
      "type": "date",
      "count": 1
    },
    {
      "text": "$10 billion",
      "type": "money",
      "count": 1
    }
  ],
  "byType": {
    "organisation": [
      "Cloudflare",
      "Microsoft",
      "OpenAI"
    ],
    "place": [
      "San Francisco"
    ],
    "product": [
      "Workers AI"
    ],
    "date": [
      "September 2023"
    ],
    "money": [
      "$10 billion"
    ]
  },
  "model": "@cf/meta/llama-3.1-8b-instruct-fp8",
  "source": {
    "chars": 115,
    "truncated": false
  }
}
```

## Related

- [POST /invoice/parse](/services/invoice-parse) ($0.02): Parse an invoice or receipt into clean JSON: supplier, VAT/tax ID, invoice number, dates, currency, line items, subtotal, tax, total, amount due and bank detail
- [POST /document/ask](/services/document-ask) ($0.02): Ask a question about one document (PDF, Word, web page or pasted text) and get a short answer with the exact quotes that support it.
- [POST /keywords](/services/keywords) ($0.003): Key phrases and topics of a text, web page or PDF, for tagging, SEO and search indexes: up to 30 key phrases, most important first, each checked by code to real
- [POST /moderate](/services/moderate) ($0.005): Content moderation for AI agents and apps: is this text safe?
- [POST /pii/redact](/services/pii-redact) ($0.005): Remove personal data from text before an agent stores it or sends it to another model: emails, phone numbers, card numbers, IBANs, NI numbers, SSNs, IP addresse
- [POST /sentiment](/services/sentiment) ($0.005): Sentiment analysis for reviews, comments, support tickets and social replies: up to 50 texts per call, each labelled positive, neutral, negative or mixed with a
- [POST /text/cluster](/services/text-cluster) ($0.01): Group similar texts: send up to 200 pieces of feedback, support tickets, reviews or survey answers and get back the groups that say much the same thing, biggest
- [POST /text/rank](/services/text-rank) ($0.003): Semantic ranking: give a query and up to 100 candidate texts (search results, FAQ answers, products, document chunks) and get them sorted by how well they match

New here? [Getting started in 60 seconds](/start). All services: [Aayat AI](/).