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

# Scheduled searches

> Monitor a company or people search: run it again every day or every week to keep finding new matches.

A search normally runs once. When you **monitor** a search, it runs again on a schedule, and each run adds companies or people that match and were not in the results before. You can run a monitored search daily or weekly.

Use it to keep a list growing without resending the request yourself: new companies hiring for a role, newly funded companies in your market, people who have just started in a job you sell to.

> [!NOTE]
>
> **You need**
>
> * An API key. See the [quickstart](https://docs.data.avina.io/quickstart.md).
> * A balance in your workspace. Every scheduled run is charged like a search. Set `max_cost_usd` to cap each run.

## Start a monitored search

Add `monitor` to the request that starts the search. The search runs straight away, then again at the frequency you chose.

```json POST /v1/companies/search theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "query": "B2B software companies in the US with 50 to 500 employees that are hiring sales development representatives",
  "limit": 25,
  "max_cost_usd": 20,
  "monitor": { "frequency": "daily" }
}
```

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://api.avina.io/v1/companies/search \
  -H "Authorization: Bearer $AVINA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "query": "B2B software companies in the US with 50 to 500 employees that are hiring sales development representatives",
    "limit": 25,
    "max_cost_usd": 20,
    "monitor": { "frequency": "daily" }
  }'
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import os, uuid, requests

API = "https://api.avina.io/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['AVINA_API_KEY']}"}

response = requests.post(
    f"{API}/companies/search",
    headers={**HEADERS, "Idempotency-Key": str(uuid.uuid4())},
    json={
        "query": "B2B software companies in the US with 50 to 500 employees "
                 "that are hiring sales development representatives",
        "limit": 25,
        "max_cost_usd": 20,
        "monitor": {"frequency": "daily"},
    },
)
response.raise_for_status()
search = response.json()
print(search["id"], search["monitor"]["next_run_at"])
```

The response is the usual search, with its schedule in `monitor`:

```json Response (shortened) theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "object": "company_search",
  "id": "32ba40da-e558-442a-8945-e93fc771afc9",
  "status": "queued",
  "limit": 25,
  "monitor": {
    "frequency": "daily",
    "status": "active",
    "runs_completed": 0,
    "last_run_at": null,
    "next_run_at": "2026-11-13T17:02:11Z"
  }
}
```

Keep the search `id`. Every run adds to this one search.

## Monitor a search you already ran

Ran a search once and liked the results? Turn monitoring on for it:

```json PUT /v1/companies/search/{search_id}/monitor theme={"theme":{"light":"github-light","dark":"github-dark"}}
{ "frequency": "weekly" }
```

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X PUT https://api.avina.io/v1/companies/search/$SEARCH_ID/monitor \
  -H "Authorization: Bearer $AVINA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "frequency": "weekly" }'
```

The companies it already found stay in the results. Later runs add to them.

## Frequencies

| `frequency` | The search runs |
| - | - |
| `daily` | Every 24 hours |
| `weekly` | Every 7 days |

The schedule is counted from the moment monitoring was turned on. `monitor.next_run_at` always shows when the next run is due. Daily and weekly are the options available today.

## What happens at each run

**1. The search starts again**

At `next_run_at`, the search's `status` goes back to `running`.

**2. It looks only for new matches**

Companies or people already in the results are skipped. They are not checked or charged for again.

**3. New matches are added to the results**

Each run adds up to `limit` new results, after the ones that were already there.

**4. The run finishes**

`status` becomes `completed`, `stop_reason` says why this run stopped, and `monitor.next_run_at` moves to the next run.

A run that finds nothing new is normal. It ends with `stop_reason: sources_exhausted` and the search tries again at the next run.

## Read what each run found

Results from every run are in one list, in the order they were found. Store the `next_cursor` you last saw and pass it as `after`, and you get only what has been added since. This is the same cursor (A marker for your position in a list. Send it back to get the items that come after it.) that [Poll and paginate](https://docs.data.avina.io/guides/poll-and-paginate.md) uses.

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
def read_new_results(search_id: str, after: str | None) -> tuple[list[dict], str]:
    """Return results added since `after`, and the cursor to store for next time."""
    new = []
    while True:
        response = requests.get(
            f"{API}/companies/search/{search_id}/results",
            headers=HEADERS,
            params={"limit": 100, **({"after": after} if after else {})},
        )
        response.raise_for_status()
        page = response.json()
        new.extend(page["data"])
        after = page["next_cursor"]
        if not page["has_more"]:
            return new, after

# Run this once a day, a little after monitor.next_run_at.
companies, cursor = read_new_results(SEARCH_ID, saved_cursor)
for company in companies:
    print(company["found_at"], company["name"], company["domain"])
save(cursor)  # store it wherever you keep state
```

Each result has a `found_at` timestamp, so you can also tell which run it came from.

> [!NOTE]
>
> Webhooks that tell you when a run has finished are [coming soon](https://docs.data.avina.io/guides/poll-and-paginate.md#webhooks). Until then, read results on your own schedule, a little after `monitor.next_run_at`.

## Control what it spends

A monitored search keeps spending until you pause or stop it, so set its limits when you create it.

| Setting | On a monitored search |
| - | - |
| `limit` | The most new results **each run** can add. |
| `max_cost_usd` | The most **each run** can spend, in US dollars. A run that reaches it stops with `stop_reason: usage_limit_reached` and keeps what it found. |

A daily search with `max_cost_usd: 20` can spend at most \$20 a day. `cost_usd` on the search is the total across all runs.

If your workspace's balance runs out, the run stops and the schedule stays in place. The search tries again at its next run.

## Pause, change or stop

| To | Send |
| - | - |
| Pause | `PUT .../monitor` with `{ "frequency": "daily", "paused": true }` |
| Resume | `PUT .../monitor` with `{ "frequency": "daily", "paused": false }` |
| Change the frequency | `PUT .../monitor` with the new `frequency` |
| Stop monitoring, keep the results | `DELETE .../monitor` |
| Stop a run in progress and the schedule | `POST .../cancel` |

Pausing keeps the schedule but skips runs. Stopping removes the schedule. In both cases, everything found so far stays readable.

## Good to know

* **The request is fixed.** A plain-language `query` is interpreted once, when the search is created, so every run checks the same requirements. To change the requirements, start a new search.
* **Contacts come with new companies.** If the search has `persona_ids`, each new company arrives with its contacts, as on a one-time search.
* **People searches work the same way.** Use `/people/search` in place of `/companies/search`. A monitored people search is a simple way to hear about people who have just started in a role.
* **It finds new matches, not changes.** A monitored search adds companies that newly match. It does not tell you when a company already in your results changes. That is what [Watch](https://docs.data.avina.io/capabilities/watch.md) is for.

## Related

* [Signals](https://docs.data.avina.io/guides/signals.md): searches worth scheduling
* [Monitor a company search](https://docs.data.avina.io/api-reference/companies/monitor-search.md) and [Monitor a people search](https://docs.data.avina.io/api-reference/people/monitor-search.md)
* [Search lifecycle](https://docs.data.avina.io/concepts/search-lifecycle.md#monitored-searches)
* [Pricing](https://docs.data.avina.io/concepts/pricing.md)


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