> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbb.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Research runs

> How a research run is planned, priced, agreed and polled over MCP, what it costs, and how long it takes.

A quick look — `orbbai_who_knows_them`, `orbbai_who_knows_someone_there` — reads a few people off the record and answers in one call. A **research run** reads everyone around a person, or the people who matter at a company, scores every tie against your goal, and ranks them. It is the deep answer, and the one that costs.

## The flow

**1. Check what is held**

`orbbai_held` lists what your account has already researched. If the subject is there, `orbbai_routes_from_research` reads it — immediately, and for free.

**2. Name the subject**

For particular people, `orbbai_people_resolve` turns names into **handles**. It returns candidates and never picks: a common name comes back as several people, and the choice is yours or your user's.

**3. Plan**

`orbbai_plan` with the goal in `ask`, and **one** of:

* `handles` — a person run, for particular people;
* `company` — who inside one company is worth going through;
* `titles` with a `country` or `cities` — a search for people nobody has named yet.

The answer is a price in Research Tokens, a time, and a `planId`. **Nothing has started.** A plan missing something comes back with `refused` naming it — a goal nobody gave, a search that says nowhere — and a second call usually settles it.

**4. Agree and start**

Put the price in front of whoever is paying, then `orbbai_run_start` with the `planId` and nothing else — so what runs is exactly what was quoted. A different set of people is a different plan, at a new price.

It answers at once, with the run `id` in the structured result. `reused: true` means a run for the same subject was already working, and you are attached to it.

**5. Poll**

`orbbai_run_status` with the run id reports progress, then the findings. Runs take minutes — poll every minute or two rather than concluding early.

`orbbai_run_stop` stops a run and keeps everything found so far. What was spent is not refunded.

**6. Read the routes**

`orbbai_routes_from_research` ranks routes out of finished research against the goal you give it, with the reasoning. It requires `ask` — with nothing to rank against, it refuses rather than ordering by nothing.

## What it costs

Planning is free. Starting spends **Research Tokens** — the plan quotes the price, and that is what is charged. Typical ranges:

| Run | Fast | Standard | Deep |
| - | - | - | - |
| Person | 1 | 4 – 12 | 4 – 18 |
| Company | 1 – 2 | 3 – 10 | 12 – 40 |
| Search | 2 – 6 | 10 – 40 | 40 – 150 |

Orbb chooses the depth unless you pass `depth`; leave it out unless your user asked. No single run can spend more than 600 tokens.

## How long it takes

| Run | Time |
| - | - |
| Person, Fast | 5 – 30 minutes, on the size of their circle |
| Person, Standard | usually about 10 minutes, up to 50 on a big circle |
| Person, Deep | usually about 35 minutes, up to 70 |
| Company | the shortlist in under a minute (up to 4 on a big company), then 15 – 60 minutes for the people chosen |
| Search | Fast under a minute; Standard about 2 minutes, up to 8; Deep about 2, up to 10 |

## Making answers better: your own side

Orbb sees the public record. Who **you** can reach through — colleagues, investors, customers, former teammates — is the half only you hold.

* `orbbai_ours_remember` records those people, up to a hundred a call, in your own words for the relationship (`"design partner"`, `"board member"`). Every later answer takes them into account, and routes through them rank first.
* On the quick looks, pass `userIs` (your user's LinkedIn URL) and `userWorksAt` (their employer). The answer then marks who is **already reachable** from your side.
* When an answer carries an `outside` block, it names what would sharpen it and which of your systems holds it. Bring what you find back in `ask`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.