> ## 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.

# Jobs and results

> Job statuses, why a run stopped, empty runs, partial results and downloads.

Every run is a job with a `job_id`. Read its state from [`GET /v1/jobs/{job_id}`](https://docs.mindcase.co/api-reference/get-job), its rows from [`GET /v1/jobs/{job_id}/results`](https://docs.mindcase.co/api-reference/get-results), or list recent runs with [`GET /v1/jobs`](https://docs.mindcase.co/api-reference/list-jobs).

## Statuses

`queued` → `running` → `completed` | `failed` | `cancelled` | `rejected_balance`

All four end states are final, so stop polling on any of them.

| Status | Meaning |
| - | - |
| `queued` | Accepted and waiting to start |
| `running` | Collecting data. `row_count: 0` while running is normal |
| `completed` | Finished. `data` holds the rows, which may be none (see below) |
| `failed` | The run couldn't finish. Read `error`, `error_code` and `retryable` |
| `cancelled` | Stopped with [`DELETE /v1/jobs/{job_id}`](https://docs.mindcase.co/api-reference/cancel-job) before it finished |
| `rejected_balance` | Refused because the wallet couldn't cover it. Top up and run again |

A run that starts and then fails is not an HTTP error: it comes back with HTTP 200 and `status: "failed"`.

## Why a run failed

| `error_code` | Retry? | Meaning |
| - | - | - |
| `invalid_input` | no | Something in your input is wrong. Fix it first |
| `location_unsupported` | no | That location can't be used |
| `target_not_found` | no | The company, page or profile doesn't exist at the source |
| `request_rejected` | no | The request was refused. `error` says why |
| `collection_timeout` | yes | Collecting this data took too long |
| `collection_failed` | yes | We couldn't collect this data |
| `insufficient_balance` | after top-up | The wallet couldn't pay for this run |
| `agent_retired` | no | This API has been removed |
| `internal_error` | see `retryable` | Something failed on our side |

`fault` says who needs to act: `input` means fix the request or add balance, `mindcase` means the problem was on our side, so follow `retryable` and contact support if it keeps failing.

## Why a run stopped

Every finished job has one `stop_reason` and a plain-English `stop_message`. Branch on `stop_reason` and show `stop_message`.

| `stop_reason` | What it means | What to do | Charged for |
| - | - | - | - |
| `completed` | Everything you asked for was delivered | Nothing | Delivered rows |
| `no_results` | No rows for this request, and that's a valid answer | Follow the `notice` | Nothing, except a flat search fee |
| `row_limit_reached` | Stopped at the row limit you set | Raise the limit for more | Delivered rows |
| `balance_exhausted` | Your balance reached \$0 mid-run | Add balance, run again for the rest | Delivered rows |
| `time_limit` | Hit a time limit | Run again, narrower if you can | Delivered rows |
| `collection_failed` | We couldn't collect this data | Try again later | Delivered rows |
| `budget_guard` | Stopped to protect you from runaway cost | Narrow the search | Delivered rows |
| `interrupted` | Our system was interrupted mid-run | Run again | Delivered rows |
| `internal_error` | Something failed on our side | Try again | Delivered rows |
| `invalid_input` | Some or all of your input couldn't be used | Fix it, then run again | Delivered rows |
| `cancelled` | The run was stopped before it finished | Nothing | Delivered rows |
| `insufficient_balance` | Your balance was too low to start | Add balance, then run again | Nothing |

A run that delivered rows is `retryable: false`, because retrying buys those rows again. To get the rest of a partial run, run it again on purpose.

## When a run finds nothing

A run that found nothing is a success: `status: "completed"`, `row_count: 0`, `stop_reason: "no_results"` and a `notice` that says what to try next, such as broader search terms, a different location, or checking a link. A target that doesn't exist (a deleted post, a private profile) and a store that doesn't deliver to the location you asked for both come back this way, and aren't charged.

A run over a list of inputs also says which inputs came back empty. The `notice` reads like "Found data for 1 of 5 links. Link 2 doesn't exist; links 3 and 5 had no data.", and `notice.details.inputs` lists each input as `{param, value, status, rows}`, where `status` is `found`, `empty`, `not_found`, `invalid_input`, `not_serviceable`, `closed` or `failed`.

## What it cost

Every finished job states its cost:

* `charged`: `true` if money left your wallet.
* `usd_charged`: the exact amount. A run that stopped partway is charged only for what it delivered.
* `billing_status`: `settled`, or `settling` if the charge hasn't landed yet. While settling, `charged` and `usd_charged` are `null`, so fetch the job again shortly.

If your wallet runs out mid-run, you still get the rows collected so far, with a `notice` explaining the balance was exhausted.

## Large results

`GET /v1/jobs/{job_id}/results` returns every row as JSON. To download a file instead:

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

`format` is `csv` (default), `json` or `xlsx`.


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