Candidates
List Candidates
List all candidates across all assessments for your organization.
GET
/
v1
/
candidates
curl "https://api.promptster.ai/v1/candidates?limit=50&offset=0" \
-H "Authorization: Bearer psk_live_abc123def456"
{
"candidates": [
{
"id": "k1a2b3c4-d5e6-7890-abcd-ef1234567890",
"key": "PST-ABCD-1234",
"candidateEmail": "[email protected]",
"candidateName": "Jane Smith",
"status": "completed",
"sessionId": "sess_abc123",
"assessmentId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"assessmentTitle": "React State Management Bug Fix",
"expiresAt": "2026-04-14T10:30:00.000Z",
"redeemedAt": "2026-04-08T09:00:00.000Z",
"completedAt": "2026-04-08T10:15:00.000Z",
"totalCostUsd": 3.42
},
{
"id": "k2b3c4d5-e6f7-8901-bcde-f12345678901",
"key": "PST-EFGH-5678",
"candidateEmail": "[email protected]",
"candidateName": "John Doe",
"status": "pending",
"sessionId": null,
"assessmentId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"assessmentTitle": "React State Management Bug Fix",
"expiresAt": "2026-04-14T10:30:00.000Z",
"redeemedAt": null,
"completedAt": null,
"totalCostUsd": 0
}
],
"total": 2,
"limit": 50,
"offset": 0
}
Returns a paginated list of all candidates (candidate keys) across all assessments, ordered by creation date. Each entry includes the linked assessment title and total token cost.
Authentication
Requires an org API key.Authorization: Bearer psk_live_...
integer
default:"50"
Number of candidates to return. Maximum 200.
integer
default:"0"
Number of candidates to skip for pagination.
array
List of candidate objects.
Show properties
Show properties
string
Candidate key record ID (UUID).
string
The candidate key (e.g.
PST-ABCD-1234).string | null
Candidate’s email address.
string | null
Candidate’s display name.
string
Key status:
pending, active, completed, or expired.string | null
Linked session ID (set when candidate starts).
string
Parent assessment ID.
string
Parent assessment title.
string
ISO 8601 expiration timestamp.
string | null
When the candidate redeemed the key.
string | null
When the candidate submitted.
number
Total LLM token cost in USD.
integer
Total number of candidates across all assessments.
integer
The limit used for this request.
integer
The offset used for this request.
{
"candidates": [
{
"id": "k1a2b3c4-d5e6-7890-abcd-ef1234567890",
"key": "PST-ABCD-1234",
"candidateEmail": "[email protected]",
"candidateName": "Jane Smith",
"status": "completed",
"sessionId": "sess_abc123",
"assessmentId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"assessmentTitle": "React State Management Bug Fix",
"expiresAt": "2026-04-14T10:30:00.000Z",
"redeemedAt": "2026-04-08T09:00:00.000Z",
"completedAt": "2026-04-08T10:15:00.000Z",
"totalCostUsd": 3.42
},
{
"id": "k2b3c4d5-e6f7-8901-bcde-f12345678901",
"key": "PST-EFGH-5678",
"candidateEmail": "[email protected]",
"candidateName": "John Doe",
"status": "pending",
"sessionId": null,
"assessmentId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"assessmentTitle": "React State Management Bug Fix",
"expiresAt": "2026-04-14T10:30:00.000Z",
"redeemedAt": null,
"completedAt": null,
"totalCostUsd": 0
}
],
"total": 2,
"limit": 50,
"offset": 0
}
curl "https://api.promptster.ai/v1/candidates?limit=50&offset=0" \
-H "Authorization: Bearer psk_live_abc123def456"
curl "https://api.promptster.ai/v1/candidates?limit=50&offset=0" \
-H "Authorization: Bearer psk_live_abc123def456"
{
"candidates": [
{
"id": "k1a2b3c4-d5e6-7890-abcd-ef1234567890",
"key": "PST-ABCD-1234",
"candidateEmail": "[email protected]",
"candidateName": "Jane Smith",
"status": "completed",
"sessionId": "sess_abc123",
"assessmentId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"assessmentTitle": "React State Management Bug Fix",
"expiresAt": "2026-04-14T10:30:00.000Z",
"redeemedAt": "2026-04-08T09:00:00.000Z",
"completedAt": "2026-04-08T10:15:00.000Z",
"totalCostUsd": 3.42
},
{
"id": "k2b3c4d5-e6f7-8901-bcde-f12345678901",
"key": "PST-EFGH-5678",
"candidateEmail": "[email protected]",
"candidateName": "John Doe",
"status": "pending",
"sessionId": null,
"assessmentId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"assessmentTitle": "React State Management Bug Fix",
"expiresAt": "2026-04-14T10:30:00.000Z",
"redeemedAt": null,
"completedAt": null,
"totalCostUsd": 0
}
],
"total": 2,
"limit": 50,
"offset": 0
}