Skip to content
Keliplay Docs

List draws

GET
/v1/game-instances/{campaignId}/winner-selection/runs
curl --request GET \
  --url https://api.keliplay.com/v1/game-instances/example/winner-selection/runs \
  --header 'Authorization: Bearer <token>'

Lists the campaign’s 100 most recent draws, newest first.

Permission: results.read.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
campaignId
required
string

The campaign’s id.

Responses

Section titled “Responses”

200

Section titled “200”

The draws.

Media typeapplication/json
object
runs
required
Array<object>
<= 100 items

One draw. Every draw is recorded and can be verified.

object
id
required
string
gameInstanceId
required
string
triggeredBy
required

When winners are drawn.

  • manual: when you call the draw operation.
  • auto_on_session_end: after each play ends.
  • auto_on_schedule: once, at scheduleAt.
string
default: manual
Allowed values: manual auto_on_session_end auto_on_schedule
triggeredByApiKeyId

The API key that triggered it, if one did.

string | null
idempotencyKey
string | null
algorithm
required

The algorithm used, as in winnerSelectionAlgorithm.

string
algorithmConfigSnapshot
required
object
maxWinners
integer
>= 1 <= 1000
tieBreak

How equal scores are ordered, for score_highest.

string
Allowed values: earliest_entry random
windowStart

Only entries made at or after this time count.

string format: date-time
windowEnd

Only entries made before this time count.

string format: date-time
entriesSnapshotCount
required

How many eligible entries the draw picked from.

integer
status
required
string
Allowed values: pending completed failed
failureReason
string | null
executedAt
string | null format: date-time
createdAt
required
string format: date-time
Example
{
  "runs": [
    {
      "id": "0192f3a1-0000-7000-8000-0000000d0001",
      "gameInstanceId": "0192f3a1-0000-7000-8000-0000000ca001",
      "triggeredBy": "manual",
      "triggeredByApiKeyId": "0192f3a1-0000-7000-8000-0000000ce001",
      "idempotencyKey": "draw-2026-10-31-final",
      "algorithm": "random_uniform",
      "algorithmConfigSnapshot": {
        "maxWinners": 3
      },
      "entriesSnapshotCount": 412,
      "status": "completed",
      "failureReason": null,
      "executedAt": "2026-10-31T18:00:01.000Z",
      "createdAt": "2026-10-31T18:00:00.000Z"
    }
  ]
}

401

Section titled “401”

The API key is missing, malformed or revoked.

Media typeapplication/json
object
error
required
object
code
required

Stable and safe to branch on.

  • invalid_request (400): the request is not valid.
  • unauthorized (401): missing, malformed or revoked API key.
  • upgrade_required (402): not in your plan, or a plan limit is reached.
  • forbidden (403): the key lacks a permission, or the action is not allowed.
  • not_found (404): nothing with that id in your account.
  • conflict (409): clashes with the current state.
  • confirmation_required (409): repeat with confirm=true. Folder deletion only.
  • rate_limited (429): wait for Retry-After seconds.
  • internal_error (500) and service_unavailable (503): try again later.
string
Allowed values: invalid_request unauthorized upgrade_required forbidden not_found conflict confirmation_required rate_limited internal_error service_unavailable
message
required

Written for a person. May change; do not parse it.

string
details
One of:
Array<object>
object
path
required

The failing field, dot separated, such as prize.label.

string
message
required
string
Example
{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or revoked API key."
  }
}

403

Section titled “403”

The API key does not carry the permission this needs, or the request is not allowed.

Media typeapplication/json
object
error
required
object
code
required

Stable and safe to branch on.

  • invalid_request (400): the request is not valid.
  • unauthorized (401): missing, malformed or revoked API key.
  • upgrade_required (402): not in your plan, or a plan limit is reached.
  • forbidden (403): the key lacks a permission, or the action is not allowed.
  • not_found (404): nothing with that id in your account.
  • conflict (409): clashes with the current state.
  • confirmation_required (409): repeat with confirm=true. Folder deletion only.
  • rate_limited (429): wait for Retry-After seconds.
  • internal_error (500) and service_unavailable (503): try again later.
string
Allowed values: invalid_request unauthorized upgrade_required forbidden not_found conflict confirmation_required rate_limited internal_error service_unavailable
message
required

Written for a person. May change; do not parse it.

string
details
One of:
Array<object>
object
path
required

The failing field, dot separated, such as prize.label.

string
message
required
string
Example
{
  "error": {
    "code": "forbidden",
    "message": "Your role does not allow this (draws.run)."
  }
}

404

Section titled “404”

Nothing with that id exists in your account.

Media typeapplication/json
object
error
required
object
code
required

Stable and safe to branch on.

  • invalid_request (400): the request is not valid.
  • unauthorized (401): missing, malformed or revoked API key.
  • upgrade_required (402): not in your plan, or a plan limit is reached.
  • forbidden (403): the key lacks a permission, or the action is not allowed.
  • not_found (404): nothing with that id in your account.
  • conflict (409): clashes with the current state.
  • confirmation_required (409): repeat with confirm=true. Folder deletion only.
  • rate_limited (429): wait for Retry-After seconds.
  • internal_error (500) and service_unavailable (503): try again later.
string
Allowed values: invalid_request unauthorized upgrade_required forbidden not_found conflict confirmation_required rate_limited internal_error service_unavailable
message
required

Written for a person. May change; do not parse it.

string
details
One of:
Array<object>
object
path
required

The failing field, dot separated, such as prize.label.

string
message
required
string
Example
{
  "error": {
    "code": "not_found",
    "message": "Channel 0192f3a1-0000-7000-8000-00000000c009 not found."
  }
}

Product tour, pricing and demos: keliplay.com