# Jobs (/docs/api/jobs)

Submit a pricing job and read your history.



Jobs are scoped per user. Every read enforces ownership — your key only
sees jobs you submitted.

## Submit [#submit]

`POST /v1/jobs` returns immediately with `job_id`, a `poll_url`, and a
`stream_url`.

```bash
curl -s https://api.orakle.xyz/v1/jobs \
  -H "X-Orakle-API-Key: $ORAKLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"request_type":"nl","query":"iPhone 15 Pro 128GB"}'
```

Poll `GET /v1/jobs/{id}` until `status` is `completed` or `failed`, or
stream events from `GET /v1/jobs/{id}/stream` (Server-Sent Events).

## List [#list]

`GET /v1/jobs` returns your jobs newest-first with cursor pagination.

| Param       | Notes                                                |
| ----------- | ---------------------------------------------------- |
| `q`         | Case-insensitive substring on the query field.       |
| `date_from` | ISO timestamp; inclusive lower bound.                |
| `date_to`   | ISO timestamp; inclusive upper bound.                |
| `limit`     | Default 50, max 200.                                 |
| `cursor`    | Opaque token from `next_cursor`. Omit on first page. |

Responses include `items[]` and `next_cursor` (`null` on the last page).