> ## Documentation Index
> Fetch the complete documentation index at: https://jesse-7a8b4a1d.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Start a search

> POST /v1/searches, the run list, and the stop call.

## `POST /v1/searches`

Send one JSON object with an `Authorization: Bearer <credential>` header.

| Field | Type | Required | Meaning |
| - | - | - | - |
| `q` | string | yes | Natural-language query, 3 to 2000 characters. |
| `target` | integer | no | How many results to try to return. Accepted range 1–50. `target` drives cost: the server keeps searching until it reaches that many rows, so a higher number means more web searches and a larger bill. Omitting the field still leaves the server default of `50`, which is the most expensive setting, so send a value you actually want. |
| `speed` | string | no | `fast` or `advanced`. Eniac sends `fast`. If you omit it, the server uses `advanced`. Fast opens only the highest-scoring half of the pages that pass each excerpt screen. Advanced opens every page that passes. Any value other than `fast` is read as `advanced`. |
| `relax` | boolean | no | Default `true`. When a filter keeps almost nobody, the server loosens that filter slightly and checks again. `false` keeps the original filters for the rest of the run. |
| `sites` | string | no | Websites or page types. Domains such as `linkedin.com, x.com` keep every search on those sites, up to 20 of them. A phrase such as `job portals, case studies` prefers those page types instead. Leave it empty to search the web. `linkedin`, `x`, and `twitter` are accepted as names; `x` and `twitter` both expand to `x.com` and `twitter.com`. |

The credential is not a field. It goes in the header, on this and on every other call.

```bash theme={null}
curl -s -X POST https://eniac.floworks.ai/v1/searches \
  -H "Authorization: Bearer $ENIAC_CREDENTIAL" \
  -H "Content-Type: application/json" \
  -d '{
        "q": "Find US Series A fintech companies that hired an ML lead in the last 90 days",
        "target": 50,
        "speed": "fast",
        "relax": true
      }'
```

`202 Accepted`:

```json theme={null}
{ "id": "6f1c0c5b9a1e4b7b8d2f3a4c5e6d7f80", "status": "running" }
```

Those two fields are the entire body. Everything else about the run is read back from `GET /v1/searches/{id}`, which is described in [The run](/run).

The `202` means the search was accepted and the money was reserved, not that it succeeded. A `q` outside 3 to 2000 characters is `422` and reserves nothing; a `q` that is only whitespace is `400`. A balance that cannot cover the \$5.00 reservation is `402`, and in that one case a terminal run row is still written, so you may see a run with status `error` that has no events. See [Errors](/errors).

<Note>
  There is no idempotency key yet. A `POST` that times out on your side may still have started a run: list your recent runs before sending it again, or you will pay for two searches.
</Note>

## Date ranges

If the query names a date range (“between January and June 2025”, “last 90 days”, “during 2024”), the server converts it to absolute dates. The start is sent to web search as a publish-date floor on discovery and on the filter that checks that event. A closed range also keeps an end date on that filter: the event itself has to fall on or before that day. You do not send dates as separate fields.

## `GET /v1/searches`

Your 50 most recent runs, newest first, as the same objects `GET /v1/searches/{id}` returns, minus `result`.

```bash theme={null}
curl -s -H "Authorization: Bearer $ENIAC_CREDENTIAL" \
  https://eniac.floworks.ai/v1/searches
```

```json theme={null}
{ "runs": [ { "id": "6f1c0c5b…", "status": "running", "query": "…" } ] }
```

That body is abbreviated: each entry carries every field in [The run](/run) except `result`. There are no paging parameters. Fifty is the limit and it is not configurable.

## `POST /v1/searches/{id}/stop`

```bash theme={null}
curl -s -X POST \
  -H "Authorization: Bearer $ENIAC_CREDENTIAL" \
  "https://eniac.floworks.ai/v1/searches/6f1c0c5b9a1e4b7b8d2f3a4c5e6d7f80/stop"
```

`202 Accepted`:

```json theme={null}
{ "id": "6f1c0c5b9a1e4b7b8d2f3a4c5e6d7f80", "status": "running", "stopRequested": true }
```

`status` is the run's status at the moment the flag was raised, so on a live run it reads `running`: the stop is a request, not a transition. Keep reading the stream, or poll the run. The run unwinds within seconds and lands as `stopped`, emitting `final` (with `stopped: true`), `cost`, `usage` and `done` for whatever had already passed the funnel. You are charged for what it spent up to that point.

Stopping a run that has already finished is also `202`, and `status` then reads the terminal state it reached. Only a run that is not yours, or does not exist, is `404`. Calling stop twice is harmless.


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