---
title: "Atomically claim logins for one run"
method: POST
path: "/v1/lists/{name}/claims"
---

# Atomically claim logins for one run

`POST /v1/lists/{name}/claims`

## Request

- Base URL: `https://api.githunt.ai`
- URL: `https://api.githunt.ai/v1/lists/{name}/claims`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-Api-Key`

Reserves identities so two runs on the same brief cannot deliver the same candidate. A login is claimable when it is not on the list or its previous claim has expired; `seen` entries and live claims come back as `unavailable` instead of being stolen. Claims expire, so an interrupted run releases its candidates and the next search can return them again. The list is created on first claim under the same plan cap as `POST /v1/lists/{name}/logins`, so a fresh brief needs no prior write; exceeding the cap is an `invalid_request`. Debits 0 monthly credits.

## Path parameters

- `name` string, required

## Request body

- object
  - `logins` string[], required
  - `ttlSeconds` integer: Claim lifetime. Out-of-range values are clamped.

## Response `200`

Claim result

- ClaimResponse
  - `success` true
  - `data` object
    - `name` string
    - `claimed` string[]: Logins this run now holds until `claim_expires_at`.
    - `unavailable` object[]: Logins another run holds, or that are already `seen`.
      - `login` string
      - `state` 'seen' | 'claimed'
      - `claim_expires_at` string, nullable
    - `claim_expires_at` string, date-time
  - `meta` Meta: Envelope metadata. `quota.cost` is 0 on endpoints that debit no credits.
    - `requestId` string
    - `quota` Quota
      - `used` integer
      - `limit` integer: -1 means unlimited
      - `month` string
      - `cost` integer: Credits this request debited (search: 1, get user: 1, evidence report: 3 when a report is returned and 0 while pending, analyze profile: 3, list operations: 0). `used` already reflects this charge.
      - `rollover` integer: Unused credits banked from the previous month and available on top of `limit` this month (`remaining` = limit + rollover - used). Only present on the Team plan, capped at one extra month's allowance (so at most 2x the allowance is usable in a month).

## Other responses

- `400`: Invalid request
- `401`: Missing, invalid, or revoked API key
- `404`: No matching developer
- `429`: Monthly or daily quota exceeded
- `500`: Unexpected server error

---

[API](https://skmtc.dev/githunt/apis/githunt-api.md) · [All operations](https://skmtc.dev/githunt/apis/githunt-api/llms.txt) · [OpenAPI document](https://skmtc.dev/githunt/apis/githunt-api/revisions/6fc325607da0?raw)