Skip to main content

Run a WHOIS batch

Batch lookups run asynchronously. Save the idempotency key before submission, then save the returned data.job_id. Keep using the same project key scope for progress, results, and cancellation.

1. Submit once​

Set ANTAPI_IDEMPOTENCY_KEY to a unique saved value for this batch:

curl --include --request POST \
  "https://api.antapi.dev/whois/v1/batches" \
  --header "Authorization: Bearer $ANTAPI_KEY" \
  --header "Idempotency-Key: $ANTAPI_IDEMPOTENCY_KEY" \
  --header "Content-Type: application/json" \
  --data '{"domains":["example.com","example.net","EXAMPLE.COM"]}'

HTTP 202 means the batch has been accepted; it does not mean processing or billing is complete. The Gateway reserves the highest authorized cost for valid, distinct normalized domains. In this input, the two forms of example.com share processing.

Read data.job_id from the response body rather than depending on a Location header. If the response is lost, retry the same submission with the same idempotency key and unchanged input. Do not create a new key to recover an uncertain request.

2. Poll progress​

Set ANTAPI_JOB_ID to the returned job ID:

curl --include \
  "https://api.antapi.dev/whois/v1/batches/$ANTAPI_JOB_ID" \
  --header "Authorization: Bearer $ANTAPI_KEY"

Jobs move through queued and running to a terminal state: completed, cancelled, failed, or expired. Honor Retry-After when returned, back off between polls, and stop polling once the job is terminal. Progress requests are free but still subject to authentication and rate limits.

3. Read result pages​

curl "https://api.antapi.dev/whois/v1/batches/$ANTAPI_JOB_ID/results" \
  --header "Authorization: Bearer $ANTAPI_KEY"

Read data.results, data.has_more, and data.next_cursor. If has_more is true, pass the returned cursor unchanged on the next request. Treat it as opaque. Set ANTAPI_CURSOR to that returned value:

curl --get \
  "https://api.antapi.dev/whois/v1/batches/$ANTAPI_JOB_ID/results" \
  --header "Authorization: Bearer $ANTAPI_KEY" \
  --data-urlencode "cursor=$ANTAPI_CURSOR"

Rows follow the original input order. Inspect each row's status, state, and optional error_code; HTTP success for a page does not mean every lookup succeeded. Duplicate inputs retain their original positions, so counting rows does not give the billable quantity. Save the results your application needs while they remain available under the API's documented retention policy.

4. Cancel remaining work​

curl --request POST \
  "https://api.antapi.dev/whois/v1/batches/$ANTAPI_JOB_ID:cancel" \
  --header "Authorization: Bearer $ANTAPI_KEY"

Cancellation is free and safe to repeat. It stops scheduling new items; in-flight work may still finish, and existing results remain available. Keep checking progress until terminal, then read the final results. Successfully completed domains are charged and unused reservation is released during settlement. Disconnecting from a request does not cancel the job.

See WHOIS response data and quality for the success definition, billing for reservations and settlement and errors for recovery after timeouts or conflicts.