Stream People

GET

api

public

people

stream

curl -N -X GET "https://app.gethuntd.com/api/v1/public/people/stream?is_user=true" \
  -H "X-API-Key: hntd_abc12345_yoursecretkey"

import readline from 'node:readline';
import { Readable } from 'node:stream';

const response = await fetch(
  'https://app.gethuntd.com/api/v1/public/people/stream?is_user=true',
  { headers: { 'X-API-Key': process.env.HUNTD_API_KEY } }
);

const lines = readline.createInterface({ input: Readable.fromWeb(response.body) });
for await (const line of lines) {
  if (!line.trim()) continue;
  const person = JSON.parse(line);
  if (person.error) throw new Error(person.error.code); // truncated stream
  handle(person);
}

import json
import os
import requests

with requests.get(
    'https://app.gethuntd.com/api/v1/public/people/stream',
    params={'is_user': 'true'},
    headers={'X-API-Key': os.environ['HUNTD_API_KEY']},
    stream=True,  # required, or requests buffers the whole body
) as response:
    for line in response.iter_lines():
        if not line:
            continue
        person = json.loads(line)
        if 'error' in person:
            raise RuntimeError(person['error']['code'])  # truncated stream
        handle(person)

{"id":"62381c7cc5fc496eff56fd60","firstName":"Ada","lastName":"Lovelace","email":"ada@acme.com","companyDomain":"acme.com","sources":["devin"],"discoveredAt":"2026-07-31T17:28:28.725Z"}
{"id":"62381c7cc5fc496eff56fd61","firstName":"Grace","lastName":"Hopper","email":"grace@globex.com","companyDomain":"globex.com","sources":[],"discoveredAt":"2026-07-31T16:02:11.402Z"}

{"id":"62381c7cc5fc496eff56fd60","firstName":"Ada","lastName":"Lovelace","email":"ada@acme.com","companyDomain":"acme.com","sources":["devin"],"discoveredAt":"2026-07-31T17:28:28.725Z"}
{"success":false,"error":{"code":"STREAM_FAILED","message":"Stream failed before completion."}}

{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "API key is missing, invalid, or has been revoked."
  }
}

{
  "success": false,
  "error": {
    "code": "SOURCE_NOT_ALLOWED",
    "message": "Your organization does not have access to source `gong`."
  }
}

Availability: Enterprise plan, on https://app.gethuntd.com. Agency keys receive 403 ENDPOINT_NOT_ON_PLAN. Uses no credits, and counts as one request against your rate limit.

curl -N -X GET "https://app.gethuntd.com/api/v1/public/people/stream?is_user=true" \
  -H "X-API-Key: hntd_abc12345_yoursecretkey"

import readline from 'node:readline';
import { Readable } from 'node:stream';

const response = await fetch(
  'https://app.gethuntd.com/api/v1/public/people/stream?is_user=true',
  { headers: { 'X-API-Key': process.env.HUNTD_API_KEY } }
);

const lines = readline.createInterface({ input: Readable.fromWeb(response.body) });
for await (const line of lines) {
  if (!line.trim()) continue;
  const person = JSON.parse(line);
  if (person.error) throw new Error(person.error.code); // truncated stream
  handle(person);
}

import json
import os
import requests

with requests.get(
    'https://app.gethuntd.com/api/v1/public/people/stream',
    params={'is_user': 'true'},
    headers={'X-API-Key': os.environ['HUNTD_API_KEY']},
    stream=True,  # required, or requests buffers the whole body
) as response:
    for line in response.iter_lines():
        if not line:
            continue
        person = json.loads(line)
        if 'error' in person:
            raise RuntimeError(person['error']['code'])  # truncated stream
        handle(person)

{"id":"62381c7cc5fc496eff56fd60","firstName":"Ada","lastName":"Lovelace","email":"ada@acme.com","companyDomain":"acme.com","sources":["devin"],"discoveredAt":"2026-07-31T17:28:28.725Z"}
{"id":"62381c7cc5fc496eff56fd61","firstName":"Grace","lastName":"Hopper","email":"grace@globex.com","companyDomain":"globex.com","sources":[],"discoveredAt":"2026-07-31T16:02:11.402Z"}

{"id":"62381c7cc5fc496eff56fd60","firstName":"Ada","lastName":"Lovelace","email":"ada@acme.com","companyDomain":"acme.com","sources":["devin"],"discoveredAt":"2026-07-31T17:28:28.725Z"}
{"success":false,"error":{"code":"STREAM_FAILED","message":"Stream failed before completion."}}

{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "API key is missing, invalid, or has been revoked."
  }
}

{
  "success": false,
  "error": {
    "code": "SOURCE_NOT_ALLOWED",
    "message": "Your organization does not have access to source `gong`."
  }
}

Overview

Returns every person matching your filters in a single response, as NDJSON: one JSON object per line, each the same shape as a data[] entry from List People. Use it for backfills and full exports. The same filters apply. Paging parameters (page, limit, skip_count) are ignored. See Streaming for when to stream rather than page.

Reading the Stream

Use a streaming line reader (curl -N, Node readline, Python iter_lines()). fetch().json(), requests.get().json() and Invoke-RestMethod buffer the entire body into memory first, which defeats the point and can run out of memory on large exports.

Expect roughly 40 to 100 rows per second: a full backfill of tens of thousands of people takes minutes, not seconds. The stream is not resumable, so a dropped connection means starting again. For very large exports, stream one discovered_from / discovered_to window at a time.

Mid-stream Errors

Once rows are flowing the HTTP status is already sent, so a failure can’t be a status code. Instead the last line is an error object and the connection closes:

{"success":false,"error":{"code":"STREAM_FAILED","message":"Stream failed before completion."}}

Treat a line with an error key as a truncated result, not data: discard or mark what you collected as partial, then retry.

Errors

Returned as a normal HTTP error, before any rows are sent:

HTTP	Error Code	Description
400	`INVALID_PARAMETER`	A query parameter is malformed or out of range
401	`INVALID_API_KEY`	API key is missing, invalid, or has been revoked
403	`ENDPOINT_NOT_ON_PLAN`	Your plan doesn’t include this endpoint (Agency keys)
403	`SUBSCRIPTION_INACTIVE`	Your workspace has no active subscription. Contact your account manager.
403	`SOURCE_NOT_ALLOWED`	Your organization doesn’t have access to the requested `source`
423	`SOURCE_UNAVAILABLE`	The requested `source` is paused for maintenance. Retry later.
429	`RATE_LIMIT_EXCEEDED`	Over 60 requests per minute. Wait `Retry-After` seconds.
500	`INTERNAL_ERROR`	Something broke on our side. Safe to retry.
503	`ORG_KIND_UNAVAILABLE`	Your plan briefly couldn’t be confirmed. Retry.

Authorizations

X-API-Key

string

header

required

API key in format: hntd_{id}_{secret}. Create one in Settings → API & webhooks. Authorization: Bearer is also accepted.

Query Parameters

discovered_days

integer

The last N UTC days, including today (2 = today and yesterday). "Discovered" means when we last checked the row, not when it was confirmed. Can't be combined with discovered_from / discovered_to.

Required range: 1 <= x <= 366

discovered_from

string<date>

Inclusive UTC start day, YYYY-MM-DD.

Example:

"2026-07-01"

discovered_to

string<date>

Inclusive UTC end day, YYYY-MM-DD.

Example:

"2026-07-31"

source

string

Restrict to one source slug, as returned by List Sources.

Example:

"gong"

is_user

enum<string>

default:all

true: confirmed users only. false: checked but not a user. all: both.

Available options:

all,

true,

false

Response

NDJSON: one person object per line, the same shape as a data[] entry from the paginated endpoint. If the stream fails after it started, the last line is an error object instead: treat it as a truncated result.

A person Huntd tracks for your organization

string

Stable identifier. Use it to deduplicate across pages and runs.

firstName

string | null

First name.

lastName

string | null

Last name.

string | null

Email address.

jobTitle

string | null

Job title as we observed it.

seniority

string | null

Derived from the job title.

department

string | null

Derived from the job title.

jobFunction

string | null

Derived from the job title.

company

string | null

Company display name.

companyDomain

string | null

Normalized domain. Joins directly to domain on List Companies.

companySize

integer | null

Employee count.

industry

string | null

Comma-separated industry labels.

location

string | null

Location as we observed it.

country

string | null

Country.

linkedinUrl

string | null

LinkedIn profile URL.

sources

string[]

Source slugs this person is a confirmed user of. Empty means we checked and found no user account, not that they are untracked.

discoveredAt

string<date-time> | null

When we last checked this person (UTC). Always agrees with the date filter, so it is safe as an incremental-sync cursor.

curl -N -X GET "https://app.gethuntd.com/api/v1/public/people/stream?is_user=true" \
  -H "X-API-Key: hntd_abc12345_yoursecretkey"

import readline from 'node:readline';
import { Readable } from 'node:stream';

const response = await fetch(
  'https://app.gethuntd.com/api/v1/public/people/stream?is_user=true',
  { headers: { 'X-API-Key': process.env.HUNTD_API_KEY } }
);

const lines = readline.createInterface({ input: Readable.fromWeb(response.body) });
for await (const line of lines) {
  if (!line.trim()) continue;
  const person = JSON.parse(line);
  if (person.error) throw new Error(person.error.code); // truncated stream
  handle(person);
}

import json
import os
import requests

with requests.get(
    'https://app.gethuntd.com/api/v1/public/people/stream',
    params={'is_user': 'true'},
    headers={'X-API-Key': os.environ['HUNTD_API_KEY']},
    stream=True,  # required, or requests buffers the whole body
) as response:
    for line in response.iter_lines():
        if not line:
            continue
        person = json.loads(line)
        if 'error' in person:
            raise RuntimeError(person['error']['code'])  # truncated stream
        handle(person)

{"id":"62381c7cc5fc496eff56fd60","firstName":"Ada","lastName":"Lovelace","email":"ada@acme.com","companyDomain":"acme.com","sources":["devin"],"discoveredAt":"2026-07-31T17:28:28.725Z"}
{"id":"62381c7cc5fc496eff56fd61","firstName":"Grace","lastName":"Hopper","email":"grace@globex.com","companyDomain":"globex.com","sources":[],"discoveredAt":"2026-07-31T16:02:11.402Z"}

{"id":"62381c7cc5fc496eff56fd60","firstName":"Ada","lastName":"Lovelace","email":"ada@acme.com","companyDomain":"acme.com","sources":["devin"],"discoveredAt":"2026-07-31T17:28:28.725Z"}
{"success":false,"error":{"code":"STREAM_FAILED","message":"Stream failed before completion."}}

{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "API key is missing, invalid, or has been revoked."
  }
}

{
  "success": false,
  "error": {
    "code": "SOURCE_NOT_ALLOWED",
    "message": "Your organization does not have access to source `gong`."
  }
}

Huntd Enterprise API

Email Check

Stream People

Overview

Reading the Stream

Mid-stream Errors

Errors

Authorizations

Query Parameters

Response

​Overview

​Reading the Stream

​Mid-stream Errors

​Errors

Authorizations

Query Parameters

Response

Overview

Reading the Stream

Mid-stream Errors

Errors