List candidates
Candidates of a position with status, current step, assignee and source.
GET https://cotlet.dev/api/v1/comeet/positions/{position_id}/candidates
read
Lists the candidates of one position, 30 to a page; pass next_cursor back as cursor. Filters match what the Recruit position view offers: status, step, step type, assignee, tag and source. waiting_since is when the candidate reached the current step. Only candidates you may see are returned; evaluations of hired candidates stay hidden for other roles.
Parameters
| Name | Type | Description |
|---|---|---|
| position_id string required | string | Position from list_positions. |
| status enum | enum | in_progress (default), on_hold, rejected, withdrawn, hired. |
| step string | string | Current workflow step name. |
| step_type enum | enum | go_no_go, interview, administrative, offer or send_notification. |
| assignee string | string | Teammate who holds the current step. |
| tag string | string | Only candidates with this tag. |
| limit integer | integer | 1 to 30. Default: 30. |
| cursor string | string | Next page cursor from the previous call. |
Request
curl https://cotlet.dev/api/v1/comeet/positions/position_8c41d2/candidates \
-H "Authorization: Bearer $COTLET_API_KEY"result = client.call("comeet", "list_candidates", {"position_id":"position_8c41d2"})const result = await cotlet.call('comeet', 'list_candidates', {"position_id":"position_8c41d2"});cotlet call comeet list_candidates --data '{"position_id":"position_8c41d2"}'Example response
{
"candidates": [
{
"candidate_id": "cand_5a11c8",
"name": "Mia Jensen",
"status": "in_progress",
"current_step": "Hiring manager screen",
"step_type": "go_no_go",
"assignee": "Dana Cho",
"source": "Careers website",
"waiting_since": "2026-10-16"
},
{
"candidate_id": "cand_7d21a9",
"name": "Noah Kim",
"status": "in_progress",
"current_step": "Application review",
"step_type": "administrative",
"assignee": "Ravi Shah",
"source": "Referral",
"waiting_since": "2026-10-02"
}
],
"next_cursor": null
}