# Rotto API

> Find anyone's work email, personal email and phone number from a LinkedIn profile link or an email address, and search Rotto's candidates from a plain-English brief. A REST API and an MCP server on one balance, paid only for details that are found.

Source: https://rotto.com/docs/api. Base URL: https://rotto.com/api/v1. OpenAPI document: https://rotto.com/api/v1/openapi.json.

Find anyone's work email, personal email and phone number from a LinkedIn profile link or an email address, and search Rotto's candidates from a plain-English brief, from your own code.

The API runs the same lookups and searches as the Rotto app and the [Rotto MCP server](https://rotto.com/mcp): the same prices, the same balance and the same contacts. Anything you look up here shows in your workspace, and anything you looked up there you can read here for free.

## Quickstart

1. **Create a key.** In Rotto, open [Settings](https://rotto.com/candidates/settings?tab=apps), then Connected apps, then Create API key. Copy it: it is shown once.
2. **Check your balance.**

```bash
curl https://rotto.com/api/v1/balance \
  -H "Authorization: Bearer $ROTTO_API_KEY"
```

3. **Look someone up.** You pay only for the details that are found.

```bash
curl https://rotto.com/api/v1/contacts/lookup \
  -H "Authorization: Bearer $ROTTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": "https://www.linkedin.com/in/ada-lovelace", "max_credits": 20}'
```

## Authentication

Send your key on every call as `Authorization: Bearer rcl_live_...`. Each key carries its own permissions, chosen when you create it:

- `lookup`: look people up and spend from your balance. Needed to look people up, reveal extras and reveal a candidate's details.
- `search`: search rotto's candidates and export them. Needed for searches and candidate profiles. A new key leaves it unticked: choose it to search from code. Anything that spends (an export, or a search answer past its free people) needs `lookup` as well.
- `read`: see your balance and contacts. Needed for the balance, estimates, lookups and contacts.

Keep keys on your server. Never put one in a web page or a mobile app, where anyone can read it. Revoke a key in Settings, Connected apps: it stops working at once. The same key also connects the MCP server.

The **Test request** button on this page sends real requests from your browser straight to Rotto with the key you type. They spend real credits, exactly as your code would. The key is not saved.

## Pricing

You pay in credits from your Rotto balance (10 credits = $1), and **only for details that are found**. A miss is free, a detail you already hold is free, and a person repeated in one call is charged once. Every amount the API returns comes in credits (`*_credits`) and in US dollars (`*_usd`). Every account pays the same price for each detail:

| Work email | Personal email | Phone | LinkedIn find | Profile only |
| --- | --- | --- | --- | --- |
| 1 credit ($0.10) | 3 credits ($0.30) | 9 credits ($0.90) | 1 credit ($0.10) | 1 credit ($0.10) |

An email input first finds the LinkedIn profile behind it: that is the LinkedIn find, charged only on a match.

## Profiles

Every found person comes with their name, headline, current company, location and LinkedIn URL. For more, pass `"include_profile": true` on a lookup (or `?include_profile=true` on `GET /lookups/{lookup_id}` and `GET /contacts`), and each found person also carries `profile`: their About, skills, work history (title, company, dates, location, description) and education, with `as_of`, when it was read from LinkedIn. `GET /contacts/{contact_id}` always returns it. The profile is free: it is what the lookup already holds.

To get the profile with no contact details, send `"channels": []`. That costs a profile's price per person found (1 credit ($0.10), the same as the LinkedIn find), for a LinkedIn URL and an email alike, and nothing for a person not found or one you already hold. A stored profile older than 30 days is read from LinkedIn again on that person's next lookup, at no cost to you.

A bigger top-up earns extra credits, by the size of that one top-up:

| One top-up of | Extra credits | That top-up buys |
| --- | --- | --- |
| $100 or more | 10% | 1,100 credits |
| $500 or more | 15% | 5,750 credits |
| $2,500 or more | 25% | 31,250 credits |

Before a lookup runs, the most it could cost (every detail found for everyone) is reserved from your balance; the unused part is released as it settles. If your balance cannot cover that, the call is refused with `402 insufficient_balance` and nothing is spent. With auto top-up on, your card tops the balance up first. Top up at [https://rotto.com/candidates/settings#balance](https://rotto.com/candidates/settings#balance).

Two guards help you control spend: `POST /estimate` prices a lookup without running it, and `max_credits` (or `max_usd`; send both and the lower applies) on any spending call refuses (with `422 over_max_usd`, spending nothing) when the most it could cost is over your limit.

## Waiting for results

Most lookups finish within a minute or two. A spending call waits up to 4 minutes and answers `200` with the results, so **set your HTTP client's timeout to at least 5 minutes**. If it is still running after that, it answers `202` with `status: "running"` and a `lookup_id`: poll `GET /lookups/{lookup_id}` every 5 to 10 seconds until `status` is `done`. Polls count toward the 30 calls a minute.

To never wait (or if your client cannot hold a request open that long), pass `"wait": false`: you get the `202` and the `lookup_id` within seconds, and the lookup runs on.

A list can also answer `202` with `status: "paused"` when an auto top-up could not run. `paused.message` says why and `paused.resume_url` is where you resume it.

## Searching candidates

Describe who you want in plain English and Rotto finds them, as the app's search does. Your key needs the `search` permission: a new key leaves it unticked, so tick it when you create the key.

1. **Start a search** with `POST /searches` and a `brief` ("Senior backend engineers in London who have worked at a fintech"). You get the first matches and a `search_id`.
2. **Get more people** with `POST /searches/{search_id}/candidates`: the next `page`, or on a plan any slice of the ranking with `offset` and `limit` (up to 1,000 people deep).
3. **Refine it** in plain English with `POST /searches/{search_id}/refine` ("only people in London"). It keeps its `search_id`.
4. **Open someone** with `GET /candidates/{candidate_id}` for their full profile, and **reveal their details** with `POST /candidates/{candidate_id}/reveal`, charged as a lookup is: only what is found, never twice.
5. **Export** the search as a CSV with `POST /searches/{search_id}/export`.

`GET /searches` lists your saved searches and `GET /searches/{search_id}` reopens one, both free. A search started here is in your Rotto app too, and the other way round.

Searching spends no credits. On the Free plan: 5 free searches. 15 people per page. Each extra page or refinement uses a search. A plan searches without a limit and gets 40 people a call for free. An answer of more than 40 people charges the people past the first 100 of a search at the export's price, 1 credit per 10, once a day: the same call again costs nothing more. An export costs the same per person, plus any contact details it finds, and needs a plan: the Free plan cannot export. A search takes up to a minute or two, so keep your HTTP client's timeout at 5 minutes. Search results never include contact details.

## Extras

Some people have more than one email or phone. Every result lists those under `extras`, each with a `key` and its `price_credits` (and `price_usd`). Reveal one with `POST /contacts/{contact_id}/extras`. It is charged once: revealing it again is free.

## Limits

| Limit | Value |
| --- | --- |
| Calls per key | 30 a minute, shared with the same key's MCP calls |
| People looked up per account | 5,000 a day (UTC), across the API and MCP |
| Inputs per batch call | 50 |
| Lookups running at once | 2 per account |
| Request body | 64 KB |

Every answer carries `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` headers. A `429` carries `Retry-After` in seconds.

Lookups that need a fresh search are paced across all accounts. At busy times a large batch takes longer to finish, but nothing fails or is charged for waiting.

## Errors

Every error is JSON with one shape (the one exception is a `405` for a method an endpoint does not take). `type` is stable: branch on it, not on `message`.

```json
{
  "error": {
    "type": "insufficient_balance",
    "message": "Your balance does not cover this lookup: it needs 13 credits if every detail is found and you have 5 credits. Top up at https://rotto.com/candidates/settings#balance. Nothing was spent.",
    "request_id": "0b6c1f0e-5d7a-4a3b-9f61-2c8e4d1a7b90",
    "required_usd": 1.3,
    "required_credits": 13,
    "available_usd": 0.5,
    "available_credits": 5,
    "load_url": "https://rotto.com/candidates/settings#balance"
  }
}
```

| Status | `type` | When |
| --- | --- | --- |
| 400 | `invalid_request` | The body or query is not valid JSON or does not match the schema. `issues` says where. |
| 400 | `invalid_input` | Nothing to look up, an extra key that is not one of the person's extras, or a search brief Rotto cannot search (`code` says `unsearchable` or `brief_too_vague`). |
| 401 | `missing_api_key` | No `Authorization: Bearer` header. |
| 401 | `invalid_api_key` | The key is unknown, revoked, or not an API key. |
| 402 | `insufficient_balance` | Your balance does not cover the most this could cost. Nothing was spent. `load_url` says where to add money. |
| 403 | `insufficient_scope` | The key was created without the scope this endpoint needs. |
| 403 | `account_frozen` | Your account is paused while a payment is reviewed. |
| 403 | `plan_limit` | Your plan does not include this, or the Free plan's candidate searches are used up. `upgrade_url` says where to choose a plan. |
| 403 | `forbidden_origin` | A browser on another website sent the request. Call the API from your server. |
| 404 | `not_found` | No such lookup, contact, search or candidate that your account can open. |
| 413 | `payload_too_large` | The body is over 64 KB. |
| 422 | `over_max_usd` | The most this could cost is over your `max_credits` or `max_usd`. Nothing was spent. |
| 429 | `rate_limited` | Too many calls a minute, people a day, or lookups running at once. See `Retry-After`. |
| 500 | `server_error` | Something went wrong on our side. Retry with backoff. |
| 503 | `service_unavailable` | We could not check your key just now. Retry with backoff. |
| 504 | `search_timeout` | A search took longer than one call can wait. `search_id` names it: get its people with POST /searches/{search_id}/candidates. |

## Retries

Retrying is safe for your balance: a detail you already hold is never charged again and a miss is never charged. Retry `429`, `500` and `503` with exponential backoff, honoring `Retry-After`. To pick up a lookup that answered `202`, poll its `lookup_id` rather than sending it again.

## Versioning

The version is in the path (`/v1`). We may add fields to responses, so ignore fields you do not know. Anything that would break your code ships as a new version.

## Use with AI tools

Press **Copy for LLM** at the top of this page to copy these docs, every endpoint and the MCP server as one Markdown file, ready to paste into an AI assistant. Tools that read docs themselves can fetch [llms.txt](https://rotto.com/docs/api/llms.txt) for an index or [llms-full.txt](https://rotto.com/docs/api/llms-full.txt) for everything.

# REST API reference

Every endpoint takes `Authorization: Bearer <API key>` and answers JSON. Paths are under `https://rotto.com/api/v1`.

## Lookups

### Look up one person

`POST https://rotto.com/api/v1/contacts/lookup`

Find one person's work email, personal email and phone number from their LinkedIn profile link or their email address. This spends credits from your balance (10 credits = $1), but only for details that are found. The price is the same for every account: a work email is 1 credit, a personal email 3 credits and a phone 9 credits. An email input also pays a work email's price to find the LinkedIn profile behind it, only when one is found; the profile alone (channels []) is 1 credit per person found. Details you already hold cost nothing. Pass `channels: []` for the profile alone (their LinkedIn, current role and location, no contact details), and `include_profile: true` to get each found person's work history, education and About under `profile`. Pass `max_credits` (or `max_usd`) to refuse anything pricier, or call POST /estimate first. Usually answers within a minute. If it is still running after 4 minutes (or you pass `wait: false`) it answers 202 with a `lookup_id` to poll.

Permission: `lookup`.

Body (JSON):

| Field | Type | Required | What it is |
| --- | --- | --- | --- |
| `input` | string | Yes | A LinkedIn profile link (linkedin.com/in/...) or an email address. |
| `channels` | array of `work_email`, `personal_email`, `phone` | No | Which details to get. Leave out for all three: work_email, personal_email, phone. Pass an empty list for the profile alone (their LinkedIn, current role and location, no contact details), charged a profile's price per person found. POST /estimate lists each price. |
| `include_profile` | boolean | No | Also return each found person's LinkedIn profile under `profile`: their About, skills, work history and education, with `as_of`, when it was read. Free. Leave out for the short answer. |
| `max_usd` | number | No | For older integrations: max_credits in US dollars. Use max_credits. With both, the lower limit applies. |
| `max_credits` | integer | No | Refuse, spending nothing, if this would cost more than this many credits with every detail found (for example 500). |
| `wait` | boolean | No | Wait up to 4 minutes for the lookup to finish (the default). Pass false to get a 202 with a lookup_id at once and poll GET /lookups/{lookup_id}. |

Example request body:

```json
{
  "input": "https://www.linkedin.com/in/ada-lovelace",
  "channels": [
    "work_email",
    "phone"
  ],
  "include_profile": true,
  "max_credits": 20
}
```

Example response (200 when done, 202 while running):

```json
{
  "status": "done",
  "lookup_id": "9b2e4d6f-1a3c-4e5b-8d7f-0c2a4e6b8d1f",
  "rotto_url": "https://rotto.com/contact-lookup/app?job=9b2e4d6f-1a3c-4e5b-8d7f-0c2a4e6b8d1f",
  "spent_usd": 1,
  "spent_credits": 10,
  "balance_usd": 19,
  "balance_credits": 190,
  "found": true,
  "person": {
    "name": "Ada Lovelace",
    "headline": "Head of Engineering at Analytical Engines",
    "company": "Analytical Engines",
    "location": "London, United Kingdom",
    "linkedin_url": "https://www.linkedin.com/in/ada-lovelace",
    "photo_url": "https://ndlmmsqcjdzyjsfwbrgb.supabase.co/storage/v1/object/public/profile-photos/ada-lovelace_profile_photo.jpg"
  },
  "values": {
    "work_email": "ada@analyticalengines.com",
    "phone": "+44 20 7946 0958"
  },
  "channels": {
    "work_email": "revealed",
    "personal_email": "not_requested",
    "phone": "revealed"
  },
  "contact_id": "3f1c2b7e-8d4a-4c1e-9b2f-6a5d4c3b2a10",
  "extras": [
    {
      "key": "email:1",
      "label": "Personal email 2",
      "price_usd": 0.3,
      "price_credits": 3,
      "revealed": false
    }
  ],
  "profile": {
    "about": "Mathematician. Wrote the first program for a machine that did not exist yet.",
    "skills": [
      "Mathematics",
      "Analytical engines",
      "Translation"
    ],
    "experience": [
      {
        "title": "Head of Engineering",
        "company": "Analytical Engines",
        "start": "Jan 2024",
        "end": null,
        "current": true,
        "location": "London, United Kingdom",
        "description": "Runs the engine programme."
      },
      {
        "title": "Mathematician",
        "company": "Independent",
        "start": "1833",
        "end": "1852",
        "current": false,
        "location": null,
        "description": null
      }
    ],
    "education": [
      {
        "school": "Home tutoring",
        "degree": null,
        "field": "Mathematics",
        "start": null,
        "end": null
      }
    ],
    "as_of": "2026-10-20T09:00:00.000Z"
  }
}
```

Errors: `400 invalid_request`, `400 invalid_input`, `401 missing_api_key`, `401 invalid_api_key`, `402 insufficient_balance`, `403 account_frozen`, `403 insufficient_scope`, `403 forbidden_origin`, `413 payload_too_large`, `422 over_max_usd`, `429 rate_limited`, `500 server_error`, `503 service_unavailable`.

### Look up up to 50 people

`POST https://rotto.com/api/v1/contacts/lookup-batch`

Find details for up to 50 people at once, each a LinkedIn profile link or an email address with an optional `id` of yours (a row number, say). Send only the rows that need details and write the answers back by id. Same prices and rules as looking up one person: The price is the same for every account: a work email is 1 credit, a personal email 3 credits and a phone 9 credits. An email input also pays a work email's price to find the LinkedIn profile behind it, only when one is found; the profile alone (channels []) is 1 credit per person found. A repeated person is looked up and charged once. Pass `channels: []` for the profile alone (their LinkedIn, current role and location, no contact details), and `include_profile: true` to get each found person's work history, education and About under `profile`. It runs as one list in your Rotto workspace. With auto top-up on, your card tops the balance up as the list runs; if a top-up cannot run, the list pauses and the answer says why (`paused`) and where you resume it.

Permission: `lookup`.

Body (JSON):

| Field | Type | Required | What it is |
| --- | --- | --- | --- |
| `inputs` | array of objects | Yes | Up to 50 people. |
| `inputs[].id` | string | No | Your own key for this row, returned with its result. |
| `inputs[].input` | string | Yes | A LinkedIn profile link or an email address. |
| `channels` | array of `work_email`, `personal_email`, `phone` | No | Which details to get. Leave out for all three: work_email, personal_email, phone. Pass an empty list for the profile alone (their LinkedIn, current role and location, no contact details), charged a profile's price per person found. POST /estimate lists each price. |
| `include_profile` | boolean | No | Also return each found person's LinkedIn profile under `profile`: their About, skills, work history and education, with `as_of`, when it was read. Free. Leave out for the short answer. |
| `max_usd` | number | No | For older integrations: max_credits in US dollars. Use max_credits. With both, the lower limit applies. |
| `max_credits` | integer | No | Refuse, spending nothing, if this would cost more than this many credits with every detail found (for example 500). |
| `wait` | boolean | No | Wait up to 4 minutes for the lookup to finish (the default). Pass false to get a 202 with a lookup_id at once and poll GET /lookups/{lookup_id}. |

Example request body:

```json
{
  "inputs": [
    {
      "id": "row-1",
      "input": "https://www.linkedin.com/in/ada-lovelace"
    },
    {
      "id": "row-2",
      "input": "charles@analyticalengines.com"
    }
  ],
  "channels": [
    "work_email"
  ],
  "max_credits": 10
}
```

Example response (200 when done, 202 while running):

```json
{
  "status": "done",
  "lookup_id": "9b2e4d6f-1a3c-4e5b-8d7f-0c2a4e6b8d1f",
  "rotto_url": "https://rotto.com/contact-lookup/app?job=9b2e4d6f-1a3c-4e5b-8d7f-0c2a4e6b8d1f",
  "spent_usd": 0.1,
  "spent_credits": 1,
  "balance_usd": 19.9,
  "balance_credits": 199,
  "results": [
    {
      "id": "row-1",
      "input": "https://www.linkedin.com/in/ada-lovelace",
      "status": "found",
      "lookup_id": "9b2e4d6f-1a3c-4e5b-8d7f-0c2a4e6b8d1f",
      "person": {
        "name": "Ada Lovelace",
        "headline": "Head of Engineering at Analytical Engines",
        "company": "Analytical Engines",
        "location": "London, United Kingdom",
        "linkedin_url": "https://www.linkedin.com/in/ada-lovelace",
        "photo_url": "https://ndlmmsqcjdzyjsfwbrgb.supabase.co/storage/v1/object/public/profile-photos/ada-lovelace_profile_photo.jpg"
      },
      "values": {
        "work_email": "ada@analyticalengines.com"
      },
      "channels": {
        "work_email": "revealed"
      },
      "contact_id": "3f1c2b7e-8d4a-4c1e-9b2f-6a5d4c3b2a10",
      "extras": []
    },
    {
      "id": "row-2",
      "input": "charles@analyticalengines.com",
      "status": "not_found",
      "reason": "No LinkedIn profile was found for this email.",
      "lookup_id": "9b2e4d6f-1a3c-4e5b-8d7f-0c2a4e6b8d1f",
      "person": null,
      "values": {},
      "channels": {},
      "extras": []
    }
  ]
}
```

Errors: `400 invalid_request`, `400 invalid_input`, `401 missing_api_key`, `401 invalid_api_key`, `402 insufficient_balance`, `403 account_frozen`, `403 insufficient_scope`, `403 forbidden_origin`, `413 payload_too_large`, `422 over_max_usd`, `429 rate_limited`, `500 server_error`, `503 service_unavailable`.

### Check a lookup

`GET https://rotto.com/api/v1/lookups/{lookup_id}`

Free. Where one of your lookups stands, by the `lookup_id` a lookup returned (or any lookup you made in the app), with each person and the details found so far. Poll it every few seconds while `status` is `running`. Add `?include_profile=true` for each found person's profile.

Permission: `read`.

Path parameters:

- `lookup_id` (string, required): The lookup_id a lookup returned.

Query parameters:

| Parameter | Type | Required | What it is |
| --- | --- | --- | --- |
| `include_profile` | `0`, `1`, `true`, `false` | No | `true` also returns each person's LinkedIn profile (About, skills, work history, education) under `profile`. Free. |

Example response (200):

```json
{
  "status": "running",
  "lookup_id": "9b2e4d6f-1a3c-4e5b-8d7f-0c2a4e6b8d1f",
  "rotto_url": "https://rotto.com/contact-lookup/app?job=9b2e4d6f-1a3c-4e5b-8d7f-0c2a4e6b8d1f",
  "spent_usd": 0.1,
  "spent_credits": 1,
  "results": [
    {
      "input": "https://www.linkedin.com/in/ada-lovelace",
      "status": "found",
      "lookup_id": "9b2e4d6f-1a3c-4e5b-8d7f-0c2a4e6b8d1f",
      "person": {
        "name": "Ada Lovelace",
        "headline": "Head of Engineering at Analytical Engines",
        "company": "Analytical Engines",
        "location": "London, United Kingdom",
        "linkedin_url": "https://www.linkedin.com/in/ada-lovelace",
        "photo_url": "https://ndlmmsqcjdzyjsfwbrgb.supabase.co/storage/v1/object/public/profile-photos/ada-lovelace_profile_photo.jpg"
      },
      "values": {
        "work_email": "ada@analyticalengines.com"
      },
      "channels": {
        "work_email": "revealed",
        "phone": "pending"
      },
      "contact_id": "3f1c2b7e-8d4a-4c1e-9b2f-6a5d4c3b2a10",
      "extras": []
    }
  ]
}
```

Errors: `400 invalid_request`, `401 missing_api_key`, `401 invalid_api_key`, `403 insufficient_scope`, `403 forbidden_origin`, `404 not_found`, `429 rate_limited`, `500 server_error`, `503 service_unavailable`.

## Contacts

### List your contacts

`GET https://rotto.com/api/v1/contacts`

Free. The people you have already looked up, newest first, optionally searched, with the details you hold for each. Re-reading them never costs anything. Add `?include_profile=true` for each person's profile.

Permission: `read`.

Query parameters:

| Parameter | Type | Required | What it is |
| --- | --- | --- | --- |
| `query` | string | No | Words to match in a name, headline, company or location. |
| `limit` | integer | No | How many to return, newest first (default 20, at most 100). |
| `include_profile` | `0`, `1`, `true`, `false` | No | `true` also returns each person's LinkedIn profile (About, skills, work history, education) under `profile`. Free. |

Example response (200):

```json
{
  "total": 1,
  "contacts": [
    {
      "person": {
        "name": "Ada Lovelace",
        "headline": "Head of Engineering at Analytical Engines",
        "company": "Analytical Engines",
        "location": "London, United Kingdom",
        "linkedin_url": "https://www.linkedin.com/in/ada-lovelace",
        "photo_url": "https://ndlmmsqcjdzyjsfwbrgb.supabase.co/storage/v1/object/public/profile-photos/ada-lovelace_profile_photo.jpg"
      },
      "values": {
        "work_email": "ada@analyticalengines.com",
        "personal_email": "ada.lovelace@gmail.com",
        "phone": "+44 20 7946 0958"
      },
      "channels": {
        "work_email": "revealed",
        "personal_email": "revealed",
        "phone": "revealed"
      },
      "contact_id": "3f1c2b7e-8d4a-4c1e-9b2f-6a5d4c3b2a10",
      "extras": [
        {
          "key": "email:1",
          "label": "Personal email 2",
          "price_usd": 0.3,
          "price_credits": 3,
          "revealed": false
        }
      ],
      "looked_up_at": "2026-10-08T14:03:11.000Z"
    }
  ]
}
```

Errors: `400 invalid_request`, `401 missing_api_key`, `401 invalid_api_key`, `403 insufficient_scope`, `403 forbidden_origin`, `429 rate_limited`, `500 server_error`, `503 service_unavailable`.

### Get one contact and their profile

`GET https://rotto.com/api/v1/contacts/{contact_id}`

Free. One person you have already looked up, by the `contact_id` a lookup or the contacts list returned: who they are, the details you hold, their extras, and their LinkedIn profile (About, skills, work history, education). Re-reading never costs anything. The profile is what the lookup stored; a copy older than 30 days is read again on the person's next lookup.

Permission: `read`.

Path parameters:

- `contact_id` (string, required): The contact_id a lookup or the contacts list returned.

Example response (200):

```json
{
  "person": {
    "name": "Ada Lovelace",
    "headline": "Head of Engineering at Analytical Engines",
    "company": "Analytical Engines",
    "location": "London, United Kingdom",
    "linkedin_url": "https://www.linkedin.com/in/ada-lovelace",
    "photo_url": "https://ndlmmsqcjdzyjsfwbrgb.supabase.co/storage/v1/object/public/profile-photos/ada-lovelace_profile_photo.jpg"
  },
  "values": {
    "work_email": "ada@analyticalengines.com",
    "personal_email": "ada.lovelace@gmail.com",
    "phone": "+44 20 7946 0958"
  },
  "channels": {
    "work_email": "revealed",
    "personal_email": "revealed",
    "phone": "revealed"
  },
  "contact_id": "3f1c2b7e-8d4a-4c1e-9b2f-6a5d4c3b2a10",
  "extras": [
    {
      "key": "email:1",
      "label": "Personal email 2",
      "price_usd": 0.3,
      "price_credits": 3,
      "revealed": false
    }
  ],
  "looked_up_at": "2026-10-08T14:03:11.000Z",
  "profile": {
    "about": "Mathematician. Wrote the first program for a machine that did not exist yet.",
    "skills": [
      "Mathematics",
      "Analytical engines",
      "Translation"
    ],
    "experience": [
      {
        "title": "Head of Engineering",
        "company": "Analytical Engines",
        "start": "Jan 2024",
        "end": null,
        "current": true,
        "location": "London, United Kingdom",
        "description": "Runs the engine programme."
      },
      {
        "title": "Mathematician",
        "company": "Independent",
        "start": "1833",
        "end": "1852",
        "current": false,
        "location": null,
        "description": null
      }
    ],
    "education": [
      {
        "school": "Home tutoring",
        "degree": null,
        "field": "Mathematics",
        "start": null,
        "end": null
      }
    ],
    "as_of": "2026-10-20T09:00:00.000Z"
  },
  "rotto_url": "https://rotto.com/contact-lookup/app?view=contacts"
}
```

Errors: `400 invalid_request`, `401 missing_api_key`, `401 invalid_api_key`, `403 insufficient_scope`, `403 forbidden_origin`, `404 not_found`, `429 rate_limited`, `500 server_error`, `503 service_unavailable`.

### Reveal an extra detail

`POST https://rotto.com/api/v1/contacts/{contact_id}/extras`

Reveal one more of a person's details, listed under `extras` in a lookup or a contact: another personal email, another work email, or a WhatsApp number that is not their phone. Each extra lists its `price_credits` (and `price_usd`). This spends credits from your balance (10 credits = $1) once: revealing it again costs nothing.

Permission: `lookup`.

Path parameters:

- `contact_id` (string, required): The contact_id a lookup or the contacts list returned.

Body (JSON):

| Field | Type | Required | What it is |
| --- | --- | --- | --- |
| `key` | string | Yes | The extra's key from that result's `extras`, like "email:1", "work_email:1" or "whatsapp". |
| `max_usd` | number | No | For older integrations: max_credits in US dollars. Use max_credits. With both, the lower limit applies. |
| `max_credits` | integer | No | Refuse, spending nothing, if this would cost more than this many credits with every detail found (for example 500). |

Example request body:

```json
{
  "key": "email:1",
  "max_credits": 10
}
```

Example response (200):

```json
{
  "key": "email:1",
  "label": "Personal email 2",
  "value": "ada@lovelace.org",
  "cost_usd": 0.3,
  "cost_credits": 3,
  "balance_usd": 19.7,
  "balance_credits": 197
}
```

Errors: `400 invalid_request`, `400 invalid_input`, `401 missing_api_key`, `401 invalid_api_key`, `402 insufficient_balance`, `403 account_frozen`, `403 insufficient_scope`, `403 forbidden_origin`, `404 not_found`, `413 payload_too_large`, `422 over_max_usd`, `429 rate_limited`, `500 server_error`, `503 service_unavailable`.

## Search

### Start a search

`POST https://rotto.com/api/v1/searches`

Search Rotto's candidates from a plain-English brief and get the first matches: each person's name, current title and company, location and candidate_id, plus a search_id for the next page, a refinement or an export. No contact details: reveal them with POST /candidates/{candidate_id}/reveal. Searching spends no credits. On the Free plan: 5 free searches. 15 people per page. Each extra page or refinement uses a search. A plan searches without a limit and gets 40 people a call for free; `limit` asks for up to 1,000, and in an answer of more than 40, people past the first 100 of a search cost 1 credit per 10, as an export does (the same call again that day costs nothing more), and need the `lookup` permission as well as `search`. Takes up to a minute or two. Needs the `search` permission.

Permission: `search`.

Body (JSON):

| Field | Type | Required | What it is |
| --- | --- | --- | --- |
| `brief` | string | Yes | Who to find, in plain English, as you would type it into Rotto: the role, seniority, location, skills, companies or industries (for example "Senior backend engineers in New York who have worked at a fintech"). A pasted job description works too. |
| `limit` | integer | No | Paid plans: how many people to return, up to 1,000 (default 40). People past the first 100 of a search cost 1 credit per 10. The Free plan always returns 15 and ignores this. |

Example request body:

```json
{
  "brief": "Senior backend engineers in London who have worked at a fintech"
}
```

Example response (200):

```json
{
  "status": "done",
  "search_id": "5d2c8e1a-7b3f-4c6d-9e0a-1f2b3c4d5e6f",
  "rotto_url": "https://rotto.com/candidates?s=5d2c8e1a-7b3f-4c6d-9e0a-1f2b3c4d5e6f",
  "summary": "Senior backend engineers in London with fintech experience",
  "offset": 0,
  "limit": 40,
  "returned": 1,
  "candidates": [
    {
      "candidate_id": "c4a1e2b3-6d5f-4a7b-8c9d-0e1f2a3b4c5d",
      "name": "Ada Lovelace",
      "title": "Senior Backend Engineer",
      "company": "Analytical Engines",
      "location": "London, United Kingdom",
      "rotto_url": "https://rotto.com/candidates/c4a1e2b3-6d5f-4a7b-8c9d-0e1f2a3b4c5d"
    }
  ],
  "total_matches": 120,
  "more_available": true,
  "next_offset": 1
}
```

Errors: `400 invalid_request`, `400 invalid_input`, `401 missing_api_key`, `401 invalid_api_key`, `402 insufficient_balance`, `403 plan_limit`, `403 insufficient_scope`, `403 forbidden_origin`, `413 payload_too_large`, `429 rate_limited`, `500 server_error`, `503 service_unavailable`, `504 search_timeout`.

### Get more people from a search

`POST https://rotto.com/api/v1/searches/{search_id}/candidates`

The next page of a search you started, or any slice of its ranking on a plan (`offset` and `limit`), or the first page of a saved search whose people are not stored. A POST because it can spend: on the Free plan each page is one of your searches, and on a plan people past the first 100 of a search are charged as an export is. Pass the same `broaden` and `hide_viewed` on every page.

Permission: `search`.

Path parameters:

- `search_id` (string, required): A search_id that starting a search or the searches list returned.

Body (JSON):

| Field | Type | Required | What it is |
| --- | --- | --- | --- |
| `page` | integer | No | Which page to return, from 1. Use page or offset, not both. |
| `offset` | integer | No | Paid plans: where to start in the search's ranking, from 0. An answer that did not fit says the next_offset to pass. Use page or offset, not both. |
| `limit` | integer | No | Paid plans: how many people to return, up to 1,000 (default 40). People past the first 100 of a search cost 1 credit per 10. The Free plan always returns 15 and ignores this. |
| `broaden` | boolean | No | Loosen the nice-to-haves to show more people (location stays), like Rotto's "see more". Keep it the same on every page of a search. |
| `hide_viewed` | boolean | No | Leave out people you have opened, in any search, this one included. Keep it the same on every page of a search. |

Example request body:

```json
{
  "offset": 40,
  "limit": 40
}
```

Example response (200):

```json
{
  "status": "done",
  "search_id": "5d2c8e1a-7b3f-4c6d-9e0a-1f2b3c4d5e6f",
  "rotto_url": "https://rotto.com/candidates?s=5d2c8e1a-7b3f-4c6d-9e0a-1f2b3c4d5e6f",
  "summary": "Senior backend engineers in London with fintech experience",
  "offset": 40,
  "limit": 40,
  "returned": 1,
  "candidates": [
    {
      "candidate_id": "c4a1e2b3-6d5f-4a7b-8c9d-0e1f2a3b4c5d",
      "name": "Ada Lovelace",
      "title": "Senior Backend Engineer",
      "company": "Analytical Engines",
      "location": "London, United Kingdom",
      "rotto_url": "https://rotto.com/candidates/c4a1e2b3-6d5f-4a7b-8c9d-0e1f2a3b4c5d"
    }
  ],
  "total_matches": null,
  "more_available": true,
  "next_offset": 41
}
```

Errors: `400 invalid_request`, `400 invalid_input`, `401 missing_api_key`, `401 invalid_api_key`, `402 insufficient_balance`, `403 plan_limit`, `403 insufficient_scope`, `403 forbidden_origin`, `404 not_found`, `413 payload_too_large`, `429 rate_limited`, `500 server_error`, `503 service_unavailable`, `504 search_timeout`.

### List your searches

`GET https://rotto.com/api/v1/searches`

Free. Your saved searches, as Rotto's Recents lists them: pinned first, then the most recently worked in, each with its search_id, name, brief and how many people matched. Older ones come a page at a time with `before`. Runs no search.

Permission: `search`.

Query parameters:

| Parameter | Type | Required | What it is |
| --- | --- | --- | --- |
| `before` | string | No | For older searches: the next_before value the last answer gave. Leave out for the most recent. |

Example response (200):

```json
{
  "status": "done",
  "searches": [
    {
      "search_id": "5d2c8e1a-7b3f-4c6d-9e0a-1f2b3c4d5e6f",
      "name": "Senior backend engineers in London with fintech experience",
      "brief": "Senior backend engineers in London who have worked at a fintech",
      "summary": "Senior backend engineers in London with fintech experience",
      "result_count": 120,
      "pinned": false,
      "last_activity_at": "2026-11-16T10:12:00.000Z",
      "rotto_url": "https://rotto.com/candidates?s=5d2c8e1a-7b3f-4c6d-9e0a-1f2b3c4d5e6f"
    }
  ],
  "more_available": false,
  "next_before": null
}
```

Errors: `400 invalid_request`, `401 missing_api_key`, `401 invalid_api_key`, `403 plan_limit`, `403 insufficient_scope`, `403 forbidden_origin`, `429 rate_limited`, `500 server_error`, `503 service_unavailable`.

### Open a search

`GET https://rotto.com/api/v1/searches/{search_id}`

Free. One saved search, as Rotto reopens it: its brief, summary, how many people matched, and its first page of people as stored when it last ran. Never runs the search: POST /searches/{search_id}/candidates does.

Permission: `search`.

Path parameters:

- `search_id` (string, required): A search_id that starting a search or the searches list returned.

Example response (200):

```json
{
  "status": "done",
  "search_id": "5d2c8e1a-7b3f-4c6d-9e0a-1f2b3c4d5e6f",
  "name": "Senior backend engineers in London with fintech experience",
  "brief": "Senior backend engineers in London who have worked at a fintech",
  "summary": "Senior backend engineers in London with fintech experience",
  "notes": null,
  "total_matches": 120,
  "created_at": "2026-11-16T10:02:00.000Z",
  "candidates": [
    {
      "candidate_id": "c4a1e2b3-6d5f-4a7b-8c9d-0e1f2a3b4c5d",
      "name": "Ada Lovelace",
      "title": "Senior Backend Engineer",
      "company": "Analytical Engines",
      "location": "London, United Kingdom",
      "rotto_url": "https://rotto.com/candidates/c4a1e2b3-6d5f-4a7b-8c9d-0e1f2a3b4c5d"
    }
  ],
  "people_stored": true,
  "rotto_url": "https://rotto.com/candidates?s=5d2c8e1a-7b3f-4c6d-9e0a-1f2b3c4d5e6f"
}
```

Errors: `400 invalid_request`, `401 missing_api_key`, `401 invalid_api_key`, `403 plan_limit`, `403 insufficient_scope`, `403 forbidden_origin`, `404 not_found`, `429 rate_limited`, `500 server_error`, `503 service_unavailable`.

### Refine a search

`POST https://rotto.com/api/v1/searches/{search_id}/refine`

Change one of your searches in plain English ("only people in London", "must have startup experience") and get its new first page, as Rotto's refine box does: the change is added to the search, which keeps its search_id. Spends no credits. On the Free plan a refined search is a new run: 5 free searches. 15 people per page. Each extra page or refinement uses a search. Retrying the same refinement is free. Takes up to a minute or two.

Permission: `search`.

Path parameters:

- `search_id` (string, required): A search_id that starting a search or the searches list returned.

Body (JSON):

| Field | Type | Required | What it is |
| --- | --- | --- | --- |
| `instruction` | string | Yes | What to change, in plain English, as you would type it into Rotto's refine box (for example "only people in London", "must have worked at a startup", "drop the Python requirement"). It is added to the search, not a new search. |
| `broaden` | boolean | No | Loosen the nice-to-haves to show more people (location stays), like Rotto's "see more". Keep it the same on every page of a search. |
| `hide_viewed` | boolean | No | Leave out people you have opened, in any search, this one included. Keep it the same on every page of a search. |
| `limit` | integer | No | Paid plans: how many people to return, up to 1,000 (default 40). People past the first 100 of a search cost 1 credit per 10. The Free plan always returns 15 and ignores this. |

Example request body:

```json
{
  "instruction": "only people who have worked at a startup"
}
```

Example response (200):

```json
{
  "status": "done",
  "search_id": "5d2c8e1a-7b3f-4c6d-9e0a-1f2b3c4d5e6f",
  "rotto_url": "https://rotto.com/candidates?s=5d2c8e1a-7b3f-4c6d-9e0a-1f2b3c4d5e6f",
  "summary": "Senior backend engineers in London with fintech experience, startup experience",
  "offset": 0,
  "limit": 40,
  "returned": 1,
  "candidates": [
    {
      "candidate_id": "c4a1e2b3-6d5f-4a7b-8c9d-0e1f2a3b4c5d",
      "name": "Ada Lovelace",
      "title": "Senior Backend Engineer",
      "company": "Analytical Engines",
      "location": "London, United Kingdom",
      "rotto_url": "https://rotto.com/candidates/c4a1e2b3-6d5f-4a7b-8c9d-0e1f2a3b4c5d"
    }
  ],
  "total_matches": 48,
  "more_available": true,
  "next_offset": 1
}
```

Errors: `400 invalid_request`, `400 invalid_input`, `401 missing_api_key`, `401 invalid_api_key`, `402 insufficient_balance`, `403 plan_limit`, `403 insufficient_scope`, `403 forbidden_origin`, `404 not_found`, `413 payload_too_large`, `429 rate_limited`, `500 server_error`, `503 service_unavailable`, `504 search_timeout`.

### Export a search as a CSV

`POST https://rotto.com/api/v1/searches/{search_id}/export`

People from one of your searches as a CSV: its top N matches or chosen candidate_ids, with their name, title, company, location, LinkedIn URL and Rotto profile. This spends credits from your balance (10 credits = $1): 1 credit per 10 people exported, plus, only if `columns` asks for work_email, personal_email or phone, each detail found at its price. Pass `estimate: true` to price it without spending, and `max_credits` to refuse anything dearer. A small CSV comes back in `csv`; every one also downloads from `download_url` for anyone signed in to your Rotto account. With contact columns it answers 202 while they are found: poll GET /lookups/{lookup_id}. Needs the `search` permission, and `lookup` too unless it is an estimate, because it spends.

Permission: `search`.

Path parameters:

- `search_id` (string, required): A search_id that starting a search or the searches list returned.

Body (JSON):

| Field | Type | Required | What it is |
| --- | --- | --- | --- |
| `top` | integer | No | Export the search's top N matches in ranked order, up to 1,000. Give this or candidate_ids. |
| `candidate_ids` | array of strings | No | Or export just these people from the search's results, by their candidate_id. |
| `columns` | array of `first_name`, `last_name`, `title`, `company`, `location`, `linkedin_url`, `headline`, `years_experience`, `rotto_profile`, `work_email`, `personal_email`, `phone` | No | The CSV's columns. Leave out for every free one: first_name, last_name, title, company, location, linkedin_url, headline, years_experience, rotto_profile. work_email, personal_email and phone are contact details, each charged at its price when found. |
| `estimate` | boolean | No | Say what this export would cost and whether the balance covers it, spending nothing. Use it before a large export. |
| `max_credits` | integer | No | Refuse, spending nothing, if this would cost more than this many credits with every detail found (for example 500). |

Example request body:

```json
{
  "top": 40,
  "max_credits": 10
}
```

Example response (200 when done, 202 while running):

```json
{
  "status": "done",
  "export_id": "e7f8a9b0-1c2d-4e3f-8a5b-6c7d8e9f0a1b",
  "people": 40,
  "omitted": 0,
  "fee_credits": 4,
  "spent_usd": 0.4,
  "spent_credits": 4,
  "balance_usd": 19.6,
  "balance_credits": 196,
  "file_name": "rotto-senior-backend-engineers.csv",
  "download_url": "https://rotto.com/api/candidates/exports/e7f8a9b0-1c2d-4e3f-8a5b-6c7d8e9f0a1b/csv",
  "csv": "first_name,last_name,title,company,location,linkedin_url\nAda,Lovelace,Senior Backend Engineer,Analytical Engines,London,https://www.linkedin.com/in/ada-lovelace\n"
}
```

Errors: `400 invalid_request`, `400 invalid_input`, `401 missing_api_key`, `401 invalid_api_key`, `402 insufficient_balance`, `403 account_frozen`, `403 plan_limit`, `403 insufficient_scope`, `403 forbidden_origin`, `404 not_found`, `413 payload_too_large`, `422 over_max_usd`, `429 rate_limited`, `500 server_error`, `503 service_unavailable`.

## Candidates

### Get a candidate's profile

`GET https://rotto.com/api/v1/candidates/{candidate_id}`

Free. One person from a search, in full: their work history, education, skills and LinkedIn About, `as_of` (when Rotto got this profile), and which contact details Rotto holds for them (and which you already own, so are free to read again). With `search_id` and `include_match_reasons=true`, which parts of that search's brief they meet. No contact details. On the Free plan only people your own searches showed you can be opened.

Permission: `search`.

Path parameters:

- `candidate_id` (string, required): A candidate_id from a search.

Query parameters:

| Parameter | Type | Required | What it is |
| --- | --- | --- | --- |
| `search_id` | string | No | The search they came from, to say why they match it (with include_match_reasons). |
| `include_bio` | `0`, `1`, `true`, `false` | No | `false` leaves out their LinkedIn About. Default true. |
| `include_match_reasons` | `0`, `1`, `true`, `false` | No | `true` says which parts of that search's brief they meet, as the Rotto card does. Needs search_id. |

Example response (200):

```json
{
  "status": "done",
  "candidate_id": "c4a1e2b3-6d5f-4a7b-8c9d-0e1f2a3b4c5d",
  "name": "Ada Lovelace",
  "title": "Senior Backend Engineer",
  "company": "Analytical Engines",
  "location": "London, United Kingdom",
  "open_to_work": false,
  "years_of_experience": 9,
  "work_history": [
    {
      "title": "Senior Backend Engineer",
      "company": "Analytical Engines",
      "start": "Mar 2021",
      "end": null,
      "current": true
    },
    {
      "title": "Backend Engineer",
      "company": "Difference Ltd",
      "start": "Jun 2016",
      "end": "Feb 2021",
      "current": false
    }
  ],
  "education": [
    {
      "school": "University of London",
      "degree": "BSc",
      "field": "Mathematics",
      "start": "2012",
      "end": "2015"
    }
  ],
  "skills": [
    "Go",
    "PostgreSQL",
    "Kafka"
  ],
  "as_of": "2026-10-30T00:00:00.000Z",
  "rotto_url": "https://rotto.com/candidates/c4a1e2b3-6d5f-4a7b-8c9d-0e1f2a3b4c5d",
  "bio": "I build payment systems that do not fall over.",
  "contact": {
    "details": [
      {
        "kind": "work_email",
        "label": "Work email",
        "owned": false,
        "verified": true
      },
      {
        "kind": "phone",
        "label": "Phone",
        "owned": false,
        "verified": false
      }
    ],
    "looking_up": [],
    "none_found": []
  }
}
```

Errors: `400 invalid_request`, `401 missing_api_key`, `401 invalid_api_key`, `403 plan_limit`, `403 insufficient_scope`, `403 forbidden_origin`, `404 not_found`, `429 rate_limited`, `500 server_error`, `503 service_unavailable`.

### Reveal a candidate's contact details

`POST https://rotto.com/api/v1/candidates/{candidate_id}/reveal`

A search result's work email, personal email, phone number or LinkedIn link, as the Rotto card gets them: details Rotto holds are revealed now, and ones it does not are looked up. This spends credits from your balance (10 credits = $1) per detail found, never for a miss, and never twice for the same detail, here, in the app or through a lookup. LinkedIn is free. The price is the same for every account: a work email is 1 credit, a personal email 3 credits and a phone 9 credits. Pass `max_credits` to refuse anything dearer. It waits up to 4 minutes for a lookup, then answers 202 with `status: "running"`: call it again later, and anything already revealed comes back free. Needs the `lookup` permission.

Permission: `lookup`.

Path parameters:

- `candidate_id` (string, required): A candidate_id from a search.

Body (JSON):

| Field | Type | Required | What it is |
| --- | --- | --- | --- |
| `channels` | array of `work_email`, `personal_email`, `phone`, `linkedin` | No | Which details to get. Leave out for work_email, personal_email and phone. A work email is 1 credit, a personal email 3, a phone 9; LinkedIn is free. Charged only when found, and never twice. |
| `all_details` | boolean | No | Reveal every detail Rotto holds in each channel (another email, a WhatsApp number), each at its price. Default: the first of each. |
| `max_credits` | integer | No | Refuse, spending nothing, if this would cost more than this many credits with every detail found (for example 500). |

Example request body:

```json
{
  "channels": [
    "work_email",
    "phone"
  ],
  "max_credits": 10
}
```

Example response (200 when done, 202 while running):

```json
{
  "status": "done",
  "candidate_id": "c4a1e2b3-6d5f-4a7b-8c9d-0e1f2a3b4c5d",
  "revealed": [
    {
      "channel": "work_email",
      "label": "Work email",
      "value": "ada@analyticalengines.com",
      "verified": true,
      "charged_credits": 1
    }
  ],
  "not_found": [
    "phone"
  ],
  "still_looking": [],
  "spent_usd": 0.1,
  "spent_credits": 1,
  "balance_usd": 19.9,
  "balance_credits": 199
}
```

Errors: `400 invalid_request`, `400 invalid_input`, `401 missing_api_key`, `401 invalid_api_key`, `402 insufficient_balance`, `403 account_frozen`, `403 plan_limit`, `403 insufficient_scope`, `403 forbidden_origin`, `404 not_found`, `413 payload_too_large`, `422 over_max_usd`, `429 rate_limited`, `500 server_error`, `503 service_unavailable`.

## Account

### Estimate a lookup's cost

`POST https://rotto.com/api/v1/estimate`

Free. The most a lookup of these inputs and details could cost, each detail's price, what you can spend, and whether it fits. Only found details are ever charged, so the real cost is usually lower.

Permission: `read`.

Body (JSON):

| Field | Type | Required | What it is |
| --- | --- | --- | --- |
| `inputs` | array of objects | Yes | Up to 50 people. |
| `inputs[].id` | string | No | Your own key for this row, returned with its result. |
| `inputs[].input` | string | Yes | A LinkedIn profile link or an email address. |
| `channels` | array of `work_email`, `personal_email`, `phone` | No | Which details to get. Leave out for all three: work_email, personal_email, phone. Pass an empty list for the profile alone (their LinkedIn, current role and location, no contact details), charged a profile's price per person found. POST /estimate lists each price. |

Example request body:

```json
{
  "inputs": [
    {
      "input": "https://www.linkedin.com/in/ada-lovelace"
    },
    {
      "input": "charles@analyticalengines.com"
    }
  ]
}
```

Example response (200):

```json
{
  "people": 2,
  "max_cost_usd": 2.7,
  "max_cost_credits": 27,
  "available_usd": 20,
  "available_credits": 200,
  "fits": true,
  "prices_usd": {
    "work_email": 0.1,
    "personal_email": 0.3,
    "phone": 0.9,
    "linkedin_from_email": 0.1,
    "profile": 0.1
  },
  "prices_credits": {
    "work_email": 1,
    "personal_email": 3,
    "phone": 9,
    "linkedin_from_email": 1,
    "profile": 1
  }
}
```

Errors: `400 invalid_request`, `401 missing_api_key`, `401 invalid_api_key`, `403 insufficient_scope`, `403 forbidden_origin`, `413 payload_too_large`, `429 rate_limited`, `500 server_error`, `503 service_unavailable`.

### Get your balance

`GET https://rotto.com/api/v1/balance`

Free. Your balance in credits (and US dollars), what each detail costs (the same price list for every account), the extra credits a bigger top-up earns, auto top-up, and the link to top up. Also your plan (Free, Starter, Professional or Business), the credits it adds each month, and on Free how many free candidate searches are left.

Permission: `read`.

Example response (200):

```json
{
  "available_usd": 20,
  "available_credits": 200,
  "balance_usd": 20,
  "balance_credits": 200,
  "frozen": false,
  "prices_usd": {
    "work_email": 0.1,
    "personal_email": 0.3,
    "phone": 0.9,
    "linkedin_from_email": 0.1,
    "profile": 0.1
  },
  "prices_credits": {
    "work_email": 1,
    "personal_email": 3,
    "phone": 9,
    "linkedin_from_email": 1,
    "profile": 1
  },
  "top_up_bonus": [
    {
      "from_usd": 100,
      "percent": 10
    },
    {
      "from_usd": 500,
      "percent": 15
    },
    {
      "from_usd": 2500,
      "percent": 25
    }
  ],
  "auto_reload": {
    "enabled": false,
    "status": "off",
    "amount_usd": 20,
    "floor_usd": 5,
    "floor_credits": 50,
    "monthly_limit_usd": null,
    "spent_this_month_usd": 0
  },
  "load_url": "https://rotto.com/contact-lookup/checkout",
  "plan": "Starter",
  "plan_status": "paid",
  "monthly_credits": 200,
  "free_searches": null
}
```

Errors: `401 missing_api_key`, `401 invalid_api_key`, `403 insufficient_scope`, `403 forbidden_origin`, `404 not_found`, `429 rate_limited`, `500 server_error`, `503 service_unavailable`.

# MCP server

Use Rotto from Claude, ChatGPT, Cursor, Claude Code, VS Code or any MCP client. The assistant finds people and looks them up for you, with the same plan, balance, prices and contacts as the app and the REST API.

## Server URL

```text
https://rotto.com/mcp
```

Every app takes this one URL. Apps that support OAuth sign you in to Rotto the first time they connect, and you choose what they may do. Anything else can send an API key instead.

## Connect your app

### Claude

1. In Claude on the web or the desktop app, open **Customize**, then **Connectors**.
2. Press **Add custom connector**.
3. Name it **Rotto** and paste the server URL.

```text
https://rotto.com/mcp
```

4. Under authentication choose **OAuth**, and leave it to register automatically.
5. Press **Connect**, sign in to Rotto and press **Allow**.

### ChatGPT

1. In ChatGPT, open **Plugins** and press **Create custom MCP server**.
2. Name it **Rotto** and paste the server URL.

```text
https://rotto.com/mcp
```

3. Sign in to Rotto when asked, and press **Allow**.

### Claude Code

1. Run this in your terminal:

```bash
claude mcp add --transport http rotto https://rotto.com/mcp
```

2. Then type **/mcp** in Claude Code, choose **rotto** and sign in to Rotto.
3. Or use an API key from Settings: set ROTTO_API_KEY to it and add this to your project's **.mcp.json**.

```json
{
  "mcpServers": {
    "rotto": {
      "type": "http",
      "url": "https://rotto.com/mcp",
      "headers": {
        "Authorization": "Bearer ${ROTTO_API_KEY}"
      }
    }
  }
}
```


### Cursor

1. [Add to Cursor](https://rotto.com/mcp): the one-click button is on the setup page.
2. Or add this to **~/.cursor/mcp.json** yourself:

```json
{
  "mcpServers": {
    "rotto": {
      "url": "https://rotto.com/mcp"
    }
  }
}
```

3. Cursor asks you to sign in to Rotto the first time it connects.

### VS Code

1. [Add to VS Code](https://vscode.dev/redirect/mcp/install?name=rotto&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Frotto.com%2Fmcp%22%7D)
2. Or add this to **.vscode/mcp.json** in your project:

```json
{
  "servers": {
    "rotto": {
      "type": "http",
      "url": "https://rotto.com/mcp"
    }
  }
}
```

3. Start the server from the file, then sign in to Rotto when VS Code asks.

### Other

1. Give your app the server URL. If it supports OAuth, it asks you to sign in to Rotto the first time it connects.

```text
https://rotto.com/mcp
```

2. If it does not, create an API key in **Settings** under Connected apps, and send it with every request:

```text
Authorization: Bearer rcl_live_YOUR_KEY
```


Then ask it: *Get the work email for linkedin.com/in/jane-doe*

## Tools

| Tool | What it does | Cost | Permission |
| --- | --- | --- | --- |
| `lookup_contact` | Look up a contact | Paid | `lookup` |
| `lookup_contacts` | Look up several contacts | Paid | `lookup` |
| `reveal_extra` | Reveal an extra detail | Paid | `lookup` |
| `search_candidates` | Search candidates | Free | `search` |
| `refine_search` | Refine a search | Free | `search` |
| `reveal_candidate_contact` | Reveal a candidate's contact details | Paid | `lookup` |
| `create_shortlist` | Create a shortlist | Free | `search` |
| `rename_shortlist` | Rename a shortlist | Free | `search` |
| `delete_shortlist` | Delete a shortlist | Free | `search` |
| `add_to_shortlist` | Add someone to a shortlist | Free | `search` |
| `remove_from_shortlist` | Take someone off a shortlist | Free | `search` |
| `move_candidate` | Move someone to a stage | Free | `search` |
| `set_candidate_status` | Save or unsave someone | Free | `search` |
| `save_note` | Write a note on someone | Free | `search` |
| `delete_note` | Delete your note on someone | Free | `search` |
| `dismiss_candidate` | Mark someone not a fit | Free | `search` |
| `export_candidates` | Export candidates | Paid | `search` |
| `list_searches` | List your searches | Free | `search` |
| `get_search` | Open a search | Free | `search` |
| `get_candidate` | Open a candidate's profile | Free | `search` |
| `list_shortlists` | List your shortlists | Free | `search` |
| `get_shortlist` | Open a shortlist | Free | `search` |
| `get_pipeline` | Show your pipeline | Free | `search` |
| `get_note` | Read your note on someone | Free | `search` |
| `estimate_cost` | Estimate the cost of a lookup | Free | `read` |
| `get_balance` | Get the balance | Free | `read` |
| `get_lookup` | Check a lookup | Free | `read` |
| `list_contacts` | List contacts | Free | `read` |
| `get_contact` | Get a contact | Free | `read` |

Paid tools spend from your balance only on the details they find. A miss, or a detail you already hold, is free. An export also costs 1 credit per 10 people in it.

### lookup_contact

Find one person's work email, personal email and phone number from their LinkedIn profile link or their email address, or just who they are (channels []): their LinkedIn, current role and location, and with include_profile their work history, education and About. This spends credits from the user's Rotto balance, but only for details that are found: a work email is 1 credit, a personal email 3 credits and a phone 9 credits, plus a work email's price to find the LinkedIn behind an email when it is found; the profile alone (channels []) is 1 credit per person found. Details the user already holds cost nothing. Call estimate_cost first when unsure, or pass max_credits. Usually answers within a minute; if not, it returns a lookup_id for get_lookup. Talk about cost in credits only, never in dollars: what a credit costs depends on the user's top-up. Each detail has one fixed price, charged only if it is found, so say "It costs 9 credits, and only if a number is found", never "up to" or "at most". In ChatGPT, personal emails can't be returned: OpenAI doesn't let apps share personal email addresses in ChatGPT. There, don't ask for personal_email. Instead say, in these words: "Rotto can get <their name>'s personal email, but OpenAI doesn't let apps share personal email addresses in ChatGPT. You can get it in Rotto in one click:" then link https://rotto.com/candidates/lookup?run=1&url= followed by the person's LinkedIn link (they sign in with their Rotto email), and mention the Rotto API at https://rotto.com/docs/api for using it in their own tools.

| Argument | Type | Required | What it is |
| --- | --- | --- | --- |
| `input` | string | Yes | A LinkedIn profile link (linkedin.com/in/...) or an email address. |
| `channels` | array of `work_email`, `personal_email`, `phone` | No | Which details to get. Leave out for all three: work_email, personal_email, phone. Pass an empty list for the profile alone (their LinkedIn, current role and location, no contact details), charged a profile's price per person found. estimate_cost lists each price. |
| `include_profile` | boolean | No | Also return each found person's LinkedIn profile under `profile`: their About, skills, work history and education, with `as_of`, when it was read. Free; it is what the lookup already holds. Leave out for the short answer. |
| `max_usd` | number | No | For older integrations: max_credits in US dollars. Use max_credits. With both, the lower limit applies. |
| `max_credits` | integer | No | Refuse, spending nothing, if this would cost more than this many credits with every detail found (for example 500). |

### lookup_contacts

Find work emails, personal emails and phone numbers for up to 50 people at once, each given as a LinkedIn profile link or an email address, or just who they are (channels []): each person's LinkedIn, current role and location, and with include_profile their work history, education and About. Use it to fill the gaps in a list: send only the rows that need details, with your own id on each, and write the answers back by id. This spends credits from the user's Rotto balance, only for details that are found: a work email is 1 credit, a personal email 3 credits and a phone 9 credits, plus a work email's price per email whose LinkedIn is found; the profile alone (channels []) is 1 credit per person found. Details the user already holds cost nothing, and a repeated person is charged once. Call estimate_cost first, or pass max_credits. If it is still running after four minutes it returns a lookup_id for get_lookup. With auto top-up on, the user's card tops the balance up as the list runs; if a top-up cannot run, the list pauses and the answer says why and where the user can resume it. Talk about cost in credits only, never in dollars: what a credit costs depends on the user's top-up. Each detail has one fixed price, charged only if it is found, so say "It costs 9 credits, and only if a number is found", never "up to" or "at most". In ChatGPT, personal emails can't be returned: OpenAI doesn't let apps share personal email addresses in ChatGPT. There, don't ask for personal_email. Instead say, in these words: "Rotto can get <their name>'s personal email, but OpenAI doesn't let apps share personal email addresses in ChatGPT. You can get it in Rotto in one click:" then link https://rotto.com/candidates/lookup?run=1&url= followed by the person's LinkedIn link (they sign in with their Rotto email), and mention the Rotto API at https://rotto.com/docs/api for using it in their own tools.

| Argument | Type | Required | What it is |
| --- | --- | --- | --- |
| `inputs` | array of objects | Yes | Up to 50 people. |
| `inputs[].id` | string | No | Your own key for this row, returned with its result. |
| `inputs[].input` | string | Yes | A LinkedIn profile link or an email address. |
| `channels` | array of `work_email`, `personal_email`, `phone` | No | Which details to get. Leave out for all three: work_email, personal_email, phone. Pass an empty list for the profile alone (their LinkedIn, current role and location, no contact details), charged a profile's price per person found. estimate_cost lists each price. |
| `include_profile` | boolean | No | Also return each found person's LinkedIn profile under `profile`: their About, skills, work history and education, with `as_of`, when it was read. Free; it is what the lookup already holds. Leave out for the short answer. |
| `max_usd` | number | No | For older integrations: max_credits in US dollars. Use max_credits. With both, the lower limit applies. |
| `max_credits` | integer | No | Refuse, spending nothing, if this would cost more than this many credits with every detail found (for example 500). |

### reveal_extra

Reveal one more of a looked-up person's details, listed under `extras` in a lookup or list_contacts result: another personal email, another work email or a WhatsApp number that is not their phone. Each extra lists its price_credits. This spends credits from the user's Rotto balance, once: revealing it again costs nothing. Pass max_credits to refuse anything pricier.

| Argument | Type | Required | What it is |
| --- | --- | --- | --- |
| `contact_id` | string | Yes | The contact_id a lookup or list_contacts returned for the person. |
| `key` | string | Yes | The extra's key from that result's `extras`, like "email:1", "work_email:1" or "whatsapp". |
| `max_usd` | number | No | For older integrations: max_credits in US dollars. Use max_credits. With both, the lower limit applies. |
| `max_credits` | integer | No | Refuse, spending nothing, if this would cost more than this many credits with every detail found (for example 500). |

### search_candidates

Search Rotto's candidates from a plain-English brief and get a page of matches: each person's name, current title and company, location, candidate_id and Rotto profile link, plus a search_id. Pass that search_id with page to get the next page. No contact details: get_candidate opens one in full, reveal_candidate_contact gets their email, phone or LinkedIn, and export_candidates takes the search_id for a CSV with LinkedIn URLs (and contact details if asked). Searching spends no credits. On the Free plan: 5 free searches. 15 people per page. Each extra page or refinement uses a search. get_balance says how many are left. A plan searches without a limit and pages 40 at a time for free; `limit` returns up to 1,000 people in one call, and in an answer of more than 40, people past the first 100 of a search cost 1 credit per 10 (the same call again that day costs nothing more). A large answer that does not fit says the next_offset to pass for the rest. Takes up to a minute or two.

| Argument | Type | Required | What it is |
| --- | --- | --- | --- |
| `brief` | string | No | Who to find, in plain English, as you would type it into Rotto: the role, seniority, location, skills, companies or industries (for example "Senior backend engineers in New York who have worked at a fintech"). A pasted job description works too. Leave it out to get another page of a search you already ran (search_id and page). |
| `search_id` | string | No | A search_id this tool returned earlier, to get another page of that search. Use it with page; leave out brief. |
| `page` | integer | No | Which page to return, from 1. A new search returns page 1; pass search_id and page 2 for the next one. |
| `limit` | integer | No | Paid plans: how many people to return, up to 1,000 (default 40, free). Above 40, people past the first 100 of a search cost 1 credit per 10, like an export. The Free plan always returns 15 a page and ignores this. |
| `offset` | integer | No | Paid plans: where to start in the search's ranking, from 0, with search_id. A large answer that did not fit says the next_offset to pass. Use either offset or page, not both. |
| `broaden` | boolean | No | With search_id: page on through the broadened list a refine_search with broaden made. Keep it the same on every page. |
| `hide_viewed` | boolean | No | With search_id: leave out people you have opened, in any search, this one included, as a refine_search with hide_viewed did. Keep it the same on every page. |

### refine_search

Change one of your searches in plain English ("only people in London", "must have startup experience") and get its new first page, as Rotto's refine box does: the change is added to the search, which keeps its search_id. Spends no credits. On the Free plan a refined search is a new run: 5 free searches. 15 people per page. Each extra page or refinement uses a search. Retrying the same refinement is free. A plan may pass limit, as with search_candidates (people past the first 100 cost 1 credit per 10). Page on with search_candidates and the same search_id (with the same broaden and hide_viewed). Takes up to a minute or two.

| Argument | Type | Required | What it is |
| --- | --- | --- | --- |
| `search_id` | string | Yes | The search to change: a search_id from search_candidates or list_searches. |
| `instruction` | string | Yes | What to change, in plain English, as you would type it into Rotto's refine box (for example "only people in London", "must have worked at a startup", "drop the Python requirement"). It is added to the search, not a new search. |
| `broaden` | boolean | No | Show more people by loosening the nice-to-haves (location stays), like Rotto's "see more". Default false. |
| `hide_viewed` | boolean | No | Leave out people you have already opened, in any search, this one included. Default false. |
| `limit` | integer | No | Paid plans: how many people to return, up to 1,000 (default 40), priced as search_candidates prices it. The Free plan always returns 15 and ignores this. |

### list_searches

Your saved Rotto searches, as Rotto's Recents lists them: pinned first, then the most recently worked in, each with its search_id, name, brief and how many people matched. Free, and runs no search. Use a search_id with search_candidates for its people, refine_search to change it, get_search to read it, or export_candidates for a CSV.

| Argument | Type | Required | What it is |
| --- | --- | --- | --- |
| `before` | string | No | For older searches: the next_before value the last answer gave. Leave out for the most recent. |

### get_search

One saved search, as Rotto reopens it: its brief, summary, how many people matched, and its first page of people as stored when it last ran. Free, and never runs the search. Use search_candidates with the search_id for more people or a fresh run, refine_search to change it, export_candidates for a CSV.

| Argument | Type | Required | What it is |
| --- | --- | --- | --- |
| `search_id` | string | Yes | A search_id from search_candidates or list_searches. |

### get_candidate

One person from search_candidates, in full: their work history, education, skills and LinkedIn About, `as_of` (when Rotto got this profile, so an older one may have changed since), which contact details Rotto holds for them (and which you already own, so are free to read again), and with search_id and include_match_reasons, which parts of that search's brief they meet. Free. No contact details: reveal_candidate_contact gets those, charged only when found. On the Free plan only people your own searches showed you can be opened.

| Argument | Type | Required | What it is |
| --- | --- | --- | --- |
| `candidate_id` | string | Yes | A candidate_id from search_candidates. |
| `search_id` | string | No | The search they came from, to say why they match it (with include_match_reasons). |
| `include_bio` | boolean | No | Include their LinkedIn About. Default true. |
| `include_match_reasons` | boolean | No | Say which parts of the search's brief they meet, as the Rotto card does. Needs search_id. Default false. |

### reveal_candidate_contact

Get a search result's work email, personal email, phone number or LinkedIn link, as the Rotto card does: details Rotto holds are revealed now, and ones it does not are looked up (it waits up to four minutes, then answers running; call again later). Charged in credits per detail found, never for a miss, and never twice for the same detail, here or in the app. Pass max_credits to refuse anything dearer. get_candidate says which details Rotto holds and which you already own. On the Free plan only people your own searches showed you can be revealed.

| Argument | Type | Required | What it is |
| --- | --- | --- | --- |
| `candidate_id` | string | Yes | A candidate_id from search_candidates. |
| `channels` | array of `work_email`, `personal_email`, `phone`, `linkedin` | No | Which details to get. Leave out for work_email, personal_email and phone. A work email is 1 credit, a personal email 3, a phone 9; LinkedIn is free. Charged only when found, and never twice. |
| `all_details` | boolean | No | Reveal every detail Rotto holds in each channel (another email, a WhatsApp number), each at its price. Default: the first of each. |
| `max_credits` | integer | No | Refuse, spending nothing, if this would cost more than this many credits with every detail found (for example 500). |

### list_shortlists

Your shortlists (the lists in Rotto's sidebar and pipeline), each with its list_id, name and how many people are on it. Free. Paid plans only.

No arguments.

### create_shortlist

Make a new shortlist, optionally with a first person on it. It appears in Rotto's sidebar and pipeline. Free. Paid plans only.

| Argument | Type | Required | What it is |
| --- | --- | --- | --- |
| `name` | string | Yes | The shortlist's name, up to 60 characters. |
| `candidate_id` | string | No | Someone to put on it straight away. |
| `search_id` | string | No | The search that person came from, as Rotto records it. Optional. |

### get_shortlist

One shortlist: its name and the candidate_id of everyone on it, newest first, with their pipeline stage. Free. get_pipeline shows the same people with their names and roles; get_candidate opens one. Paid plans only.

| Argument | Type | Required | What it is |
| --- | --- | --- | --- |
| `list_id` | string | Yes | A list_id from list_shortlists or create_shortlist. |

### rename_shortlist

Rename one of your shortlists. Free. Paid plans only.

| Argument | Type | Required | What it is |
| --- | --- | --- | --- |
| `list_id` | string | Yes | A list_id from list_shortlists or create_shortlist. |
| `name` | string | Yes | The shortlist's name, up to 60 characters. |

### delete_shortlist

Delete one of your shortlists and take everyone off it, in Rotto too. The people themselves, their notes and statuses stay. Cannot be undone. Paid plans only.

| Argument | Type | Required | What it is |
| --- | --- | --- | --- |
| `list_id` | string | Yes | A list_id from list_shortlists or create_shortlist. |

### add_to_shortlist

Put a candidate on one of your shortlists, keeping any other shortlists they are on. Free. Paid plans only.

| Argument | Type | Required | What it is |
| --- | --- | --- | --- |
| `list_id` | string | Yes | A list_id from list_shortlists or create_shortlist. |
| `candidate_id` | string | Yes | A candidate_id from search_candidates, get_shortlist or get_pipeline. |
| `search_id` | string | No | The search they came from, as Rotto records a save. Optional. |

### remove_from_shortlist

Take a candidate off one of your shortlists (their notes and status stay, and so do their other shortlists). Paid plans only.

| Argument | Type | Required | What it is |
| --- | --- | --- | --- |
| `list_id` | string | Yes | A list_id from list_shortlists or create_shortlist. |
| `candidate_id` | string | Yes | A candidate_id from search_candidates, get_shortlist or get_pipeline. |
| `search_id` | string | No | The search they came from, as Rotto records a save. Optional. |

### get_pipeline

Your Rotto pipeline: everyone you have saved, with their name, title, stage and the search they came from, as the app's board shows them. Narrow it to one shortlist, one search or one stage. Free. Paid plans only.

| Argument | Type | Required | What it is |
| --- | --- | --- | --- |
| `list_id` | string | No | Only the people on this shortlist (with its own stages, when it has custom columns). |
| `search_id` | string | No | Only the people saved from this search. |
| `stage` | string | No | Only the people in this stage, by key: shortlisted, contacted, replied, scheduled_call, screened, submitted, stage_1, stage_2, offer, hired, rejected, stay_in_touch, backburner, archived (or a shortlist's own column key). |

### move_candidate

Move a saved candidate to another pipeline stage (Contacted, Replied, Offer, Hired and so on), as dragging their card in Rotto does. They must be in your pipeline already: set_candidate_status or add_to_shortlist puts them there. Free. Paid plans only.

| Argument | Type | Required | What it is |
| --- | --- | --- | --- |
| `candidate_id` | string | Yes | A candidate_id from search_candidates, get_pipeline or get_shortlist. |
| `stage` | string | Yes | The stage to move them to, by key: shortlisted, contacted, replied, scheduled_call, screened, submitted, stage_1, stage_2, offer, hired, rejected, stay_in_touch, backburner, archived. On a shortlist with custom columns, its own column key. |
| `search_id` | string | No | The search they were saved from, as Rotto keeps one status per search. Leave out for their status outside any search. |
| `list_id` | string | No | The shortlist whose board they are moved on (needed for its custom columns). |

### set_candidate_status

Put a candidate in your pipeline (shortlisted), mark them contacted, or take them off the board (none), as the save and contacted buttons on a Rotto card do. Kept per search when search_id is given. Free. Paid plans only.

| Argument | Type | Required | What it is |
| --- | --- | --- | --- |
| `candidate_id` | string | Yes | A candidate_id from search_candidates, get_pipeline or get_shortlist. |
| `status` | `shortlisted`, `contacted`, `none` | Yes | shortlisted puts them in your pipeline, contacted marks them contacted, none takes them off the board (a note stays). |
| `search_id` | string | No | The search they were saved from, as Rotto keeps one status per search. Leave out for their status outside any search. |

### get_note

Your private note on a candidate, as written on their Rotto card. Free. Paid plans only.

| Argument | Type | Required | What it is |
| --- | --- | --- | --- |
| `candidate_id` | string | Yes | A candidate_id from search_candidates, get_pipeline or get_shortlist. |

### save_note

Write your private note on a candidate (one per person, so it replaces any note already there; get_note reads it first). It shows on their Rotto card. Free. Paid plans only.

| Argument | Type | Required | What it is |
| --- | --- | --- | --- |
| `candidate_id` | string | Yes | A candidate_id from search_candidates, get_pipeline or get_shortlist. |
| `text` | string | Yes | The note, up to 2,000 characters. It replaces any note you have on them. |

### delete_note

Delete your private note on a candidate. Cannot be undone. Paid plans only.

| Argument | Type | Required | What it is |
| --- | --- | --- | --- |
| `candidate_id` | string | Yes | A candidate_id from search_candidates, get_pipeline or get_shortlist. |

### dismiss_candidate

Mark a candidate not a fit for one search, as dismissing their card in Rotto does, so the app hides them in that search and its exports; dismissed false brings them back. Free. Paid plans only.

| Argument | Type | Required | What it is |
| --- | --- | --- | --- |
| `candidate_id` | string | Yes | A candidate_id from search_candidates, get_pipeline or get_shortlist. |
| `search_id` | string | Yes | The search they are not a fit for (dismissing is per search, as in the app). |
| `dismissed` | boolean | No | false brings them back. Default true. |

### export_candidates

Export people from one of the user's searches (search_candidates' search_id) as a CSV: its top N matches or chosen candidate_ids, with their name, title, company, location, LinkedIn URL and Rotto profile. Exporting needs a Rotto plan: on the Free plan it is refused with the plans link. This spends credits from the user's Rotto balance: 1 credit per 10 people exported (9 people is 1 credit, 11 is 2), plus, only if work_email, personal_email or phone are among the columns, each contact detail found at its price (estimate_cost lists them). Pass estimate: true first to see the cost without spending, or max_credits to refuse anything pricier. Free columns answer the CSV at once (inline and as a download link for a browser signed in to Rotto); contact columns start a run whose progress get_lookup reports by the returned lookup_id, and the same link downloads the CSV once it finishes. Talk about cost in credits only.

| Argument | Type | Required | What it is |
| --- | --- | --- | --- |
| `search_id` | string | Yes | The search_id search_candidates returned, or the id of a search in the Rotto app (yours only). |
| `top` | integer | No | Export the search's top N matches in ranked order, up to 1,000. Give this or candidate_ids. |
| `candidate_ids` | array of strings | No | Or export just these people from the search's results, by the candidate_id search_candidates returned. |
| `columns` | array of `first_name`, `last_name`, `title`, `company`, `location`, `linkedin_url`, `headline`, `years_experience`, `rotto_profile`, `work_email`, `personal_email`, `phone` | No | The CSV's columns. Leave out for every free one: first_name, last_name, title, company, location, linkedin_url, headline, years_experience, rotto_profile. work_email, personal_email and phone are contact details, each charged at its price when found. |
| `estimate` | boolean | No | Say what this export would cost and whether the balance covers it, spending nothing. Use it before a large export. |
| `max_credits` | integer | No | Refuse, spending nothing, if this would cost more than this many credits with every detail found (for example 500). |

### estimate_cost

Free. What a lookup_contact or lookup_contacts call with these inputs and channels costs in credits if every detail is found, each detail's price (and the profile-only price, for channels []), the user's available balance, and whether it fits. A detail that isn't found costs nothing. For one person and one detail, that is simply the detail's price, charged only if found.

| Argument | Type | Required | What it is |
| --- | --- | --- | --- |
| `inputs` | array of objects | Yes | Up to 50 people. |
| `inputs[].id` | string | No | Your own key for this row, returned with its result. |
| `inputs[].input` | string | Yes | A LinkedIn profile link or an email address. |
| `channels` | array of `work_email`, `personal_email`, `phone` | No | Which details to get. Leave out for all three: work_email, personal_email, phone. Pass an empty list for the profile alone (their LinkedIn, current role and location, no contact details), charged a profile's price per person found. estimate_cost lists each price. |

### get_balance

Free. The user's Rotto balance in credits: what they can spend now, what each detail costs (one price list for everyone), the extra credits a bigger top-up earns, auto top-up, and a link to top up. Also their plan (Free, Starter, Professional or Business), the credits it adds each month, and on Free how many of the free candidate searches are left.

No arguments.

### get_lookup

Free. The current state of one of the user's lookups by its lookup_id: whether it is still running, and each person with the details found so far. Pass include_profile for each found person's work history, education and About.

| Argument | Type | Required | What it is |
| --- | --- | --- | --- |
| `lookup_id` | string | Yes | The lookup_id a lookup tool returned. |
| `include_profile` | boolean | No | Also return each found person's LinkedIn profile under `profile`: their About, skills, work history and education, with `as_of`, when it was read. Free; it is what the lookup already holds. Leave out for the short answer. |

### list_contacts

Free. The people the user has already looked up on Rotto, newest first, with the emails and phone numbers they already hold. Re-reading these never costs anything. Pass include_profile for each person's work history, education and About.

| Argument | Type | Required | What it is |
| --- | --- | --- | --- |
| `query` | string | No | Words to match in a name, headline, company or location. |
| `limit` | integer | No | How many to return, newest first (default 20, at most 100). |
| `include_profile` | boolean | No | Also return each found person's LinkedIn profile under `profile`: their About, skills, work history and education, with `as_of`, when it was read. Free; it is what the lookup already holds. Leave out for the short answer. |

### get_contact

Free. One person the user has already looked up, by contact_id: who they are, the emails and phone numbers the user holds, their extras, and their LinkedIn profile (About, skills, work history, education). Re-reading never costs anything.

| Argument | Type | Required | What it is |
| --- | --- | --- | --- |
| `contact_id` | string | Yes | The contact_id a lookup or list_contacts returned for the person. |

## MCP authentication

- **OAuth**: the app opens Rotto, you sign in and press Allow. Access lasts until you revoke it.
- **API key**: the same keys the REST API uses, sent as `Authorization: Bearer rcl_live_YOUR_KEY`.

Either way, a connection only does what you allowed:

- `lookup`: look people up and spend from your balance. On the MCP server it also allows searching, as it always has.
- `search`: search rotto's candidates and export them, and work with shortlists, the pipeline and notes.
- `read`: see your balance and contacts.

Revoke any app or key in [Settings](https://rotto.com/contact-lookup/settings), under Connected apps. It stops at once.

## MCP pricing and limits

The MCP server and the REST API are one product with one balance: the same prices (see **Pricing** above) and the same limits (see **Limits** above). A key's calls a minute and an account's people a day are shared between them, not counted twice.
