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.

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:

{ "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.

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.

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.

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.

curl -s -H "Authorization: Bearer $ENIAC_CREDENTIAL" \
  https://eniac.floworks.ai/v1/searches

{ "runs": [ { "id": "6f1c0c5b…", "status": "running", "query": "…" } ] }

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

POST /v1/searches/{id}/stop

curl -s -X POST \
  -H "Authorization: Bearer $ENIAC_CREDENTIAL" \
  "https://eniac.floworks.ai/v1/searches/6f1c0c5b9a1e4b7b8d2f3a4c5e6d7f80/stop"

202 Accepted:

{ "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.