Predictions API

Retrieve a page of prediction history. The response includes predictions submitted through both the API and web interface.

Note: Request up to 100 records at a time. Generated media URLs are temporary, so download outputs you need to retain.

Prediction history is intended for browsing and synchronization. To track a newly submitted task or retrieve its final outputs, use the data.urls.get URL returned by submission, or call GET /api/v3/predictions/{task-id}/result. Do not poll the history endpoint for task status.

Endpoint

POST https://api.wavespeed.ai/api/v3/predictions

Request


curl --fail-with-body --connect-timeout 10 --max-time 60 \
--request POST "https://api.wavespeed.ai/api/v3/predictions" \
--header "Authorization: Bearer $WAVESPEED_API_KEY" \
--header "Content-Type: application/json" \
--data '{"page": 1, "page_size": 20}'

Both page and page_size are required. Start with page: 1 and increment page to retrieve subsequent results.

Response

{
  "code": 200,
  "message": "success",
  "data": {
    "page": 1,
    "items": [
      {
        "id": "e6832d4abffb4d79bfbca19783fca133",
        "model": "wavespeed-ai/z-image/turbo",
        "outputs": [
          "https://cdn.wavespeed.ai/outputs/example.jpeg"
        ],
        "urls": {
          "get": "https://api.wavespeed.ai/api/v3/predictions/e6832d4abffb4d79bfbca19783fca133/result"
        },
        "status": "completed",
        "created_at": "2025-05-19T06:09:15.948268264Z",
        "error": "",
        "executionTime": 25729,
        "timings": {
          "inference": 25729
        }
      }
    ]
  }
}

Parameters

Parameter	Type	Required	Default	Description
`page`	integer	Yes	-	Page number, starting at 1; values above 100 are capped at 100
`page_size`	integer	Yes	-	Number of records to return, from 1 to 100
`uuid`	string	No	-	Filter by an exact prediction UUID
`model`	string	No	-	Filter by model UUID
`status`	string	No	-	One of `created`, `processing`, `completed`, `failed`, `cancelled`, `timeout`, or `deleted`
`created_after`	string	No	-	RFC 3339 timestamp, for example `2025-10-01T00:00:00Z`
`created_before`	string	No	-	RFC 3339 timestamp; must be later than `created_after`

Cursor pagination

For long-running synchronization jobs, use POST /api/v3/predictions/scroll. The first request only needs page_size:

curl --fail-with-body --connect-timeout 10 --max-time 60 \
  --request POST "https://api.wavespeed.ai/api/v3/predictions/scroll" \
  --header "Authorization: Bearer $WAVESPEED_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"page_size": 20}'

When data.has_more is true, pass data.next_cursor unchanged as cursor in the next request. Do not parse the cursor or replace it with a database ID.

Overview