Conventions - Huntd

Everything on this page applies to every Public API endpoint.

Response envelope

Successful responses carry success: true. List endpoints add pagination and data.

{
  "success": true,
  "pagination": { "page": 1, "limit": 100, "total": 842, "totalPages": 9 },
  "data": []
}

Errors carry success: false:

{
  "success": false,
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "`limit` may not exceed 1000."
  }
}

Pagination

integer

default:"1"

1-indexed page number. Applies to /people and /companies.

integer

default:"100"

Results per page. Maximum 1000 — a higher value returns 400 INVALID_PARAMETER rather than being silently clamped.

integer

Set to 1 to skip the count query. total and totalPages return null, which is faster on large result sets.

Walking every page

# Page through until fewer than `limit` rows come back
curl "https://app.gethuntd.com/api/v1/public/people?page=1&limit=1000" \
  -H "X-API-Key: hntd_abc12345_yoursecretkey"

const key = process.env.HUNTD_API_KEY;
const base = 'https://app.gethuntd.com/api/v1/public/people';
const all = [];

for (let page = 1; ; page++) {
  const res = await fetch(`${base}?page=${page}&limit=1000`, {
    headers: { 'X-API-Key': key }
  });
  const body = await res.json();
  if (!body.success) throw new Error(body.error.code);

  all.push(...body.data);
  if (page >= body.pagination.totalPages) break;
}

import os
import requests

key = os.environ['HUNTD_API_KEY']
base = 'https://app.gethuntd.com/api/v1/public/people'
all_people = []
page = 1

while True:
    body = requests.get(
        base,
        params={'page': page, 'limit': 1000},
        headers={'X-API-Key': key}
    ).json()
    if not body['success']:
        raise RuntimeError(body['error']['code'])

    all_people.extend(body['data'])
    if page >= body['pagination']['totalPages']:
        break
    page += 1

For a full backfill, prefer streaming — one request instead of dozens, and it cannot miss rows the way offset paging can when data shifts mid-walk.

Date filtering

All dates are UTC.

integer

Last N UTC days, including today. Maximum 366.

string

Inclusive UTC day in YYYY-MM-DD format.

string

Inclusive UTC day in YYYY-MM-DD format.

Use either discovered_days or the discovered_from/discovered_to pair — never both, which returns 400. Either bound may be given on its own.

“Discovered” means when we last checked a person or company against a source — not when they were confirmed as a user.Someone we checked yesterday who turned out not to be a user still matches discovered_days=2, and their sources array will be empty. Add is_user=true when you want confirmed users only.

Filtering

string

A source slug from /sources.

string

default:"all"

true returns confirmed users only. false returns people we checked who are not users. Omit for both.

# People confirmed as Devin users in the last 7 days
curl "https://app.gethuntd.com/api/v1/public/people?source=devin&is_user=true&discovered_days=7" \
  -H "X-API-Key: hntd_abc12345_yoursecretkey"

Rate limits

60 requests per minute per key. Every response carries:

Header	Description
`X-RateLimit-Limit`	Requests allowed per window
`X-RateLimit-Remaining`	Requests left in the current window
`X-RateLimit-Reset`	When the window resets, Unix seconds

A 429 response adds Retry-After.

A streaming request counts as one unit against this limit no matter how long it runs.

Error codes

Status	Code	Meaning
400	`INVALID_PARAMETER`	Malformed or out-of-range query parameter
401	`INVALID_API_KEY`	Key missing, malformed, unknown, or revoked
403	`ENDPOINT_NOT_ON_PLAN`	Your plan doesn’t include this endpoint. Agency keys can only call the Email Check endpoints; other keys can’t call them.
403	`SOURCE_NOT_ALLOWED`	Your organization is not entitled to the requested `source`
403	`SUBSCRIPTION_INACTIVE`	Your workspace has no active subscription. Keys stop working when dashboard login does. Contact your account manager.
423	`SOURCE_UNAVAILABLE`	Source is temporarily under maintenance
429	`RATE_LIMIT_EXCEEDED`	Over 60/min — see `Retry-After`
500	`INTERNAL_ERROR`	Our problem
503	`ORG_KIND_UNAVAILABLE`	We briefly couldn’t confirm your plan. Retry.

Each endpoint’s page in the API Reference tab lists exactly which of these it can return. Always branch on error.code rather than the human-readable error.message, which may change.

​Response envelope

​Pagination

​Walking every page

​Date filtering

​Filtering

​Rate limits

​Error codes

Response envelope

Pagination

Walking every page

Date filtering

Filtering

Rate limits

Error codes