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

# Running an API

> One-request runs with wait=true, polling for long jobs, and safe retries.

Every API runs as a job. You can get the rows in one request with `?wait=true`, or start the job and poll for it. Use `wait=true` by default and poll when you expect a run to take minutes.

## One request: `?wait=true`

```bash theme={null}
curl -X POST "https://api.mindcase.co/v1/data/linkedin/profiles/run?wait=true" \
  -H "Authorization: Bearer $MINDCASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"params": {"queries": ["https://www.linkedin.com/in/williamhgates"]}}'
```

```json theme={null}
{
  "job_id": "7f3a1c2e-0b9d-4c55-9a51-3f2e8d1b6a40",
  "agent": "linkedin/profiles",
  "status": "completed",
  "row_count": 1,
  "returned": 1,
  "truncated": false,
  "data": [{ "firstName": "Bill", "lastName": "Gates", "headline": "...", "followers": 35000000 }]
}
```

* **60-second ceiling.** If the job hasn't finished, you get `{ "job_id": "...", "status": "running" }`. Nothing is lost: the job keeps running, so poll it with that `job_id`. Lower the ceiling with `&wait_timeout=15`.
* **First 100 rows inline.** Bigger results come back with `"truncated": true`. Fetch the rest from [`GET /v1/jobs/{job_id}/results`](https://docs.mindcase.co/api-reference/get-results) or [download them](https://docs.mindcase.co/api-reference/download.md).
* **Failures come back at once** as `status: "failed"` with `error`, `error_code` and `retryable`, still with HTTP 200. See [Jobs and results](https://docs.mindcase.co/jobs.md).

## Start and poll

For long runs, drop `wait` and poll.

**1. Start the job**

```bash theme={null}
curl -X POST https://api.mindcase.co/v1/data/linkedin/profiles/run \
  -H "Authorization: Bearer $MINDCASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"params": {"queries": ["https://www.linkedin.com/in/williamhgates", "https://www.linkedin.com/in/satyanadella"]}}'
```

```json theme={null}
{ "job_id": "7f3a1c2e-...", "agent": "linkedin/profiles", "status": "queued", "created_at": "2026-11-17T09:30:00Z" }
```

**2. Poll for results every 2 seconds**

```bash theme={null}
curl https://api.mindcase.co/v1/jobs/7f3a1c2e-.../results \
  -H "Authorization: Bearer $MINDCASE_API_KEY"
```

While the job runs you get `{ "status": "running", "row_count": 0 }`. That is normal, not an error. Stop polling on any end state: `completed`, `failed`, `cancelled` or `rejected_balance`.

Polling has its own, much larger [rate limit](https://docs.mindcase.co/rate-limits.md) and never uses up your allowance for starting runs.

## A helper you can copy

It runs with `wait=true` and only falls back to polling when the job is still going or the result was truncated.

```python Python theme={null}
import os, time, requests

API = "https://api.mindcase.co/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['MINDCASE_API_KEY']}"}
END = ("failed", "cancelled", "rejected_balance")

def run(agent, params, poll=2.0, timeout=600):
    r = requests.post(f"{API}/data/{agent}/run", params={"wait": "true"},
                      json={"params": params}, headers=HEADERS).json()
    job_id = r["job_id"]
    if r.get("status") == "completed" and not r.get("truncated"):
        return r["data"]
    if r.get("status") in END:
        raise RuntimeError(r.get("error") or r["status"])
    deadline = time.time() + timeout
    while time.time() < deadline:
        r = requests.get(f"{API}/jobs/{job_id}/results", headers=HEADERS).json()
        if r["status"] == "completed":
            return r["data"]
        if r["status"] in END:
            raise RuntimeError(r.get("error") or r["status"])
        time.sleep(poll)
    raise TimeoutError("job still running")

rows = run("google-maps/places", {"keywords": "coffee", "location": "San Francisco, USA", "maxResults": 20})
```

```javascript Node.js theme={null}
const API = "https://api.mindcase.co/v1";
const HEADERS = {
  Authorization: `Bearer ${process.env.MINDCASE_API_KEY}`,
  "Content-Type": "application/json",
};
const END = ["failed", "cancelled", "rejected_balance"];

async function run(agent, params, { poll = 2000, timeoutMs = 600000 } = {}) {
  let r = await (await fetch(`${API}/data/${agent}/run?wait=true`, {
    method: "POST", headers: HEADERS, body: JSON.stringify({ params }),
  })).json();
  const jobId = r.job_id;
  if (r.status === "completed" && !r.truncated) return r.data;
  if (END.includes(r.status)) throw new Error(r.error || r.status);
  const deadline = Date.now() + timeoutMs;
  while (Date.now() < deadline) {
    r = await (await fetch(`${API}/jobs/${jobId}/results`, { headers: HEADERS })).json();
    if (r.status === "completed") return r.data;
    if (END.includes(r.status)) throw new Error(r.error || r.status);
    await new Promise((res) => setTimeout(res, poll));
  }
  throw new Error(`timed out: ${jobId}`);
}

const rows = await run("google-maps/places", { keywords: "coffee", location: "San Francisco, USA", maxResults: 20 });
```

> [!TIP]
>
> Running thousands of jobs? Keep `wait=true` and run a bounded pool of 20 to 50 requests in flight, rather than firing everything and polling each job.

## Inputs

Send inputs under `params`. Each API's page lists the keys it accepts, which are required, their types and allowed values. Any other key is rejected with `422 invalid_params`, so don't copy extra keys from a sample.

Most APIs take a row limit such as `maxResults`, `maxItems` or `maxReviews`. Set it to cap how many rows, and how much money, a run uses. To see an API's full schema, including every allowed value:

```bash theme={null}
curl "https://api.mindcase.co/v1/data/linkedin/profiles?expand=options"
```

## Retrying safely: `Idempotency-Key`

If a `POST .../run` times out or the connection drops, you can't tell whether the run started. Send an `Idempotency-Key` header with a unique value per run, and the same value when you retry.

```bash theme={null}
curl -X POST "https://api.mindcase.co/v1/data/linkedin/profiles/run" \
  -H "Authorization: Bearer $MINDCASE_API_KEY" \
  -H "Idempotency-Key: 3f1c9a2e-7b4d-4e0a-9c1f-2d8e6b5a4c37" \
  -H "Content-Type: application/json" \
  -d '{"params": {"queries": ["https://www.linkedin.com/in/williamhgates"]}}'
```

* A retry with the same key within 24 hours returns the original job with header `X-Idempotent-Replay: true`. No new run, no new charge.
* The same key with a different API or different params returns `422 idempotency_key_reused`.
* A request that was rejected (`402`, or `422` for bad params) booked nothing, so you can fix it and retry with the same key.

## Request IDs

Every response carries an `X-Request-ID` header; on errors the same value is in `error.request_id`. Quote it when you contact support. You can send your own `X-Request-ID` (8 to 64 letters, digits, `.`, `_` or `-`) and we'll use it.


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