API reference

Jobs

Copy as Markdown

# Jobs

## Retrieve a job

`GET /v1/simulations/jobs/{job_id}`

Poll your request's result_url to settle its reserved price on first delivery and replay that delivery for free.

Authentication: Bearer API key with `simulations.run`; active Plus or Pro plan required.

### Parameters

#### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `job_id` | string | Yes | Job ID returned by your simulation request. |

#### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `reservation_id` | string | No | Request value; maximum length: 100. |
| `reservation_id` | string | Conditional | Preserve this value from result_url to select your request's funding when requests share a job. |

#### Body parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| — | — | — | None. |

### Example request

```bash
curl 'https://api.opono.com/v1/simulations/jobs/job_example?reservation_id=reservationexample' \
  --header "Authorization: Bearer $OPONO_API_KEY"
```

### Response

| Field | Type | Description |
| --- | --- | --- |
| `object` | string | simulation_job while pending or terminal; simulation when delivered. |
| `job_id` | string | Current job ID. |
| `fixture_id` | integer | Fixture ID when present. |
| `status` | string | queued or leased on 202; failed or superseded on a terminal 200. |
| `reservation_id` | string | Your credit reservation when present. |
| `result_url` | string | Request-bound delivery path when present; preserve its query string. |
| `price` | object | Number of simulated matches and exact credit price when present. |
| `credits_reserved` | number | Credits held for your request when present. |
| `retry_after_seconds` | integer | Wait this many seconds before your next poll on 202. |
| `scope / inputs / warnings` | string / object / array | Run scope, normalized inputs and non-blocking lineup warnings when present. |
| `superseded_job_id` | string | Previous job ID; equals job_id when no replacement exists. |
| `error` | object | Code and message for a failed job. |
| `simulation` | object | Present on delivery; see the [simulation response](/docs/reference/simulations#response). |

### Example response

200 response for a failed job; a successful 200 uses the [simulation response](/docs/reference/simulations#response).

```json
{
  "object": "simulation_job",
  "job_id": "job_example",
  "fixture_id": 19609874,
  "status": "failed",
  "error": {
    "code": "simulation_failed",
    "message": "The simulation could not be completed. Submit a new request for the current fixture inputs."
  }
}
```

202 response.

```json
{
  "object": "simulation_job",
  "job_id": "job_example",
  "fixture_id": 19609874,
  "reservation_id": "reservationexample",
  "result_url": "/v1/simulations/jobs/job_example?reservation_id=reservationexample",
  "status": "queued",
  "price": {
    "draws": 1000,
    "credits": "1.000"
  },
  "credits_reserved": 1,
  "retry_after_seconds": 10
}
```

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `parameter_invalid` | A parameter has an invalid value. |
| 401 | `invalid_api_key` | The credential cannot authenticate. |
| 401 | `key_revoked` | The API key has been revoked. |
| 401 | `key_expired` | The API key has expired. |
| 403 | `scope_missing` | The key lacks the required scope. |
| 403 | `tier_restricted` | The organisation plan does not include this operation. |
| 403 | `org_suspended` | Your account is suspended. |
| 403 | `ip_not_allowed` | The caller is outside the key's IP allowlist. |
| 429 | `rate_limited` | A request or authentication rate limit was exceeded. |
| 503 | `dependency_unavailable` | Request admission is unavailable. |
| 503 | `maintenance` | The API is paused for maintenance. |
| 404 | `resource_missing` | The resource is missing or belongs to another account. |
| 404 | `fixture_not_found` | No matching simulation fixture exists. |
| 409 | `reservation_expired` | The simulation credit hold ended without delivery. |
| 402 | `balance_too_low` | Your available balance cannot cover the request. |
| 400 | `fixture_not_covered` | The requested fixture is not available for simulation. |
| 503 | `refreshing` | The request can't be checked right now. |
| 503 | `settlement_unknown` | Delivery settlement could not be confirmed. |

## Retrieve a batch

`GET /v1/simulations/batches/{batch_id}`

Read your batch's per-fixture status and delivery links at zero credits.

Authentication: Bearer API key with `simulations.run`; active Plus or Pro plan required.

### Parameters

#### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `batch_id` | string | Yes | Batch ID returned by your batch request. |

#### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| — | — | — | None. |

#### Body parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| — | — | — | None. |

### Example request

```bash
curl 'https://api.opono.com/v1/simulations/batches/batch_example' \
  --header "Authorization: Bearer $OPONO_API_KEY"
```

### Response

| Field | Type | Description |
| --- | --- | --- |
| `object` | string | simulation_batch. |
| `batch_id` | string | Your batch ID. |
| `items` | array | Per-fixture jobs and reservations. |
| `items[].fixture` | integer | Fixture ID. |
| `items[].job_id` | string | Job ID for this fixture. |
| `items[].status` | string | Current item status. |
| `items[].credits_reserved` | number | Credits held for this item. |
| `items[].reservation_id` | string | Request-bound reservation when present on submission. |
| `items[].result_url` | string | Follow this path to deliver and settle the item. |
| `items[].error` | object | Error code and message when an item is unavailable. |
| `items[].credits_charged` | number | Settled credits when present on a status response. |
| `items[].freshness` | object | Freshness state and check times when present on a status response. |
| `items[].scope / inputs / warnings` | string / object / array | Each item's run scope, normalized inputs and lineup warnings when present. |
| `validUntil` | number or null | Earliest item freshness deadline in Unix milliseconds when present. |
| `credits_reserved_total` | number | Total credits reserved for this batch when present. |

### Example response

200 response.

```json
{
  "object": "simulation_batch",
  "batch_id": "batch_example",
  "items": [
    {
      "fixture": 19609874,
      "job_id": "job_example",
      "status": "queued",
      "credits_reserved": 1,
      "result_url": "/v1/simulations/jobs/job_example?reservation_id=reservationexample",
      "credits_charged": 0,
      "freshness": {
        "status": "fresh",
        "reason": "Inputs as of 2026-10-17T07:10:00.000Z.",
        "evaluatedAt": 1792310400000,
        "validUntil": 1792336499999,
        "inputsAsOf": 1792307400000
      }
    }
  ],
  "credits_reserved_total": 1,
  "validUntil": 1792336499999
}
```

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `parameter_invalid` | A parameter has an invalid value. |
| 401 | `invalid_api_key` | The credential cannot authenticate. |
| 401 | `key_revoked` | The API key has been revoked. |
| 401 | `key_expired` | The API key has expired. |
| 403 | `scope_missing` | The key lacks the required scope. |
| 403 | `tier_restricted` | The organisation plan does not include this operation. |
| 403 | `org_suspended` | Your account is suspended. |
| 403 | `ip_not_allowed` | The caller is outside the key's IP allowlist. |
| 429 | `rate_limited` | A request or authentication rate limit was exceeded. |
| 503 | `dependency_unavailable` | Request admission is unavailable. |
| 503 | `maintenance` | The API is paused for maintenance. |
| 404 | `resource_missing` | The resource is missing or belongs to another account. |
| 400 | `fixture_not_covered` | The requested fixture is not available for simulation. |
| 503 | `refreshing` | The request can't be checked right now. |
| 404 | `fixture_not_found` | No matching simulation fixture exists. |

Retrieve a job

GET /v1/simulations/jobs/{job_id}

Poll your request's result_url to settle its reserved price on first delivery and replay that delivery for free.

Authentication: Bearer API key with simulations.run; active Plus or Pro plan required.

Parameters

Path parameters

Name	Type	Required	Description
`job_id`	string	Yes	Job ID returned by your simulation request.

Query parameters

Name	Type	Required	Description
`reservation_id`	string	No	Request value; maximum length: 100.
`reservation_id`	string	Conditional	Preserve this value from result_url to select your request's funding when requests share a job.

Body parameters

Name	Type	Required	Description
—	—	—	None.

Example request

bash

curl 'https://api.opono.com/v1/simulations/jobs/job_example?reservation_id=reservationexample' \
  --header "Authorization: Bearer $OPONO_API_KEY"

Response

Field	Type	Description
`object`	string	simulation_job while pending or terminal; simulation when delivered.
`job_id`	string	Current job ID.
`fixture_id`	integer	Fixture ID when present.
`status`	string	queued or leased on 202; failed or superseded on a terminal 200.
`reservation_id`	string	Your credit reservation when present.
`result_url`	string	Request-bound delivery path when present; preserve its query string.
`price`	object	Number of simulated matches and exact credit price when present.
`credits_reserved`	number	Credits held for your request when present.
`retry_after_seconds`	integer	Wait this many seconds before your next poll on 202.
`scope / inputs / warnings`	string / object / array	Run scope, normalized inputs and non-blocking lineup warnings when present.
`superseded_job_id`	string	Previous job ID; equals job_id when no replacement exists.
`error`	object	Code and message for a failed job.
`simulation`	object	Present on delivery; see the simulation response.

Example response

200 response for a failed job; a successful 200 uses the simulation response.

json

{
  "object": "simulation_job",
  "job_id": "job_example",
  "fixture_id": 19609874,
  "status": "failed",
  "error": {
    "code": "simulation_failed",
    "message": "The simulation could not be completed. Submit a new request for the current fixture inputs."
  }
}

202 response.

json

{
  "object": "simulation_job",
  "job_id": "job_example",
  "fixture_id": 19609874,
  "reservation_id": "reservationexample",
  "result_url": "/v1/simulations/jobs/job_example?reservation_id=reservationexample",
  "status": "queued",
  "price": {
    "draws": 1000,
    "credits": "1.000"
  },
  "credits_reserved": 1,
  "retry_after_seconds": 10
}

Errors

Status	Code	Meaning
400	`parameter_invalid`	A parameter has an invalid value.
401	`invalid_api_key`	The credential cannot authenticate.
401	`key_revoked`	The API key has been revoked.
401	`key_expired`	The API key has expired.
403	`scope_missing`	The key lacks the required scope.
403	`tier_restricted`	The organisation plan does not include this operation.
403	`org_suspended`	Your account is suspended.
403	`ip_not_allowed`	The caller is outside the key's IP allowlist.
429	`rate_limited`	A request or authentication rate limit was exceeded.
503	`dependency_unavailable`	Request admission is unavailable.
503	`maintenance`	The API is paused for maintenance.
404	`resource_missing`	The resource is missing or belongs to another account.
404	`fixture_not_found`	No matching simulation fixture exists.
409	`reservation_expired`	The simulation credit hold ended without delivery.
402	`balance_too_low`	Your available balance cannot cover the request.
400	`fixture_not_covered`	The requested fixture is not available for simulation.
503	`refreshing`	The request can't be checked right now.
503	`settlement_unknown`	Delivery settlement could not be confirmed.

Retrieve a batch

GET /v1/simulations/batches/{batch_id}

Read your batch's per-fixture status and delivery links at zero credits.

Authentication: Bearer API key with simulations.run; active Plus or Pro plan required.

Parameters

Path parameters

Name	Type	Required	Description
`batch_id`	string	Yes	Batch ID returned by your batch request.

Query parameters

Name	Type	Required	Description
—	—	—	None.

Body parameters

Name	Type	Required	Description
—	—	—	None.

Example request

bash

curl 'https://api.opono.com/v1/simulations/batches/batch_example' \
  --header "Authorization: Bearer $OPONO_API_KEY"

Response

Field	Type	Description
`object`	string	simulation_batch.
`batch_id`	string	Your batch ID.
`items`	array	Per-fixture jobs and reservations.
`items[].fixture`	integer	Fixture ID.
`items[].job_id`	string	Job ID for this fixture.
`items[].status`	string	Current item status.
`items[].credits_reserved`	number	Credits held for this item.
`items[].reservation_id`	string	Request-bound reservation when present on submission.
`items[].result_url`	string	Follow this path to deliver and settle the item.
`items[].error`	object	Error code and message when an item is unavailable.
`items[].credits_charged`	number	Settled credits when present on a status response.
`items[].freshness`	object	Freshness state and check times when present on a status response.
`items[].scope / inputs / warnings`	string / object / array	Each item's run scope, normalized inputs and lineup warnings when present.
`validUntil`	number or null	Earliest item freshness deadline in Unix milliseconds when present.
`credits_reserved_total`	number	Total credits reserved for this batch when present.

Example response

200 response.

json

{
  "object": "simulation_batch",
  "batch_id": "batch_example",
  "items": [
    {
      "fixture": 19609874,
      "job_id": "job_example",
      "status": "queued",
      "credits_reserved": 1,
      "result_url": "/v1/simulations/jobs/job_example?reservation_id=reservationexample",
      "credits_charged": 0,
      "freshness": {
        "status": "fresh",
        "reason": "Inputs as of 2026-10-17T07:10:00.000Z.",
        "evaluatedAt": 1792310400000,
        "validUntil": 1792336499999,
        "inputsAsOf": 1792307400000
      }
    }
  ],
  "credits_reserved_total": 1,
  "validUntil": 1792336499999
}

Errors

Status	Code	Meaning
400	`parameter_invalid`	A parameter has an invalid value.
401	`invalid_api_key`	The credential cannot authenticate.
401	`key_revoked`	The API key has been revoked.
401	`key_expired`	The API key has expired.
403	`scope_missing`	The key lacks the required scope.
403	`tier_restricted`	The organisation plan does not include this operation.
403	`org_suspended`	Your account is suspended.
403	`ip_not_allowed`	The caller is outside the key's IP allowlist.
429	`rate_limited`	A request or authentication rate limit was exceeded.
503	`dependency_unavailable`	Request admission is unavailable.
503	`maintenance`	The API is paused for maintenance.
404	`resource_missing`	The resource is missing or belongs to another account.
400	`fixture_not_covered`	The requested fixture is not available for simulation.
503	`refreshing`	The request can't be checked right now.
404	`fixture_not_found`	No matching simulation fixture exists.