> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gethuntd.com/llms.txt
> Use this file to discover all available pages before exploring further.
# List Sources
> The sources Huntd tracks for your organization, with counts
**Availability:** Enterprise plan, on `https://app.gethuntd.com`. Agency keys receive
`403 ENDPOINT_NOT_ON_PLAN`. Uses no credits.
```bash cURL theme={null}
curl -X GET "https://app.gethuntd.com/api/v1/public/sources" \
-H "X-API-Key: hntd_abc12345_yoursecretkey"
```
```javascript JavaScript theme={null}
const response = await fetch('https://app.gethuntd.com/api/v1/public/sources', {
headers: { 'X-API-Key': process.env.HUNTD_API_KEY }
});
const { sources } = await response.json();
console.log(sources.map((s) => s.source)); // slugs to pass as ?source=
```
```python Python theme={null}
import requests
import os
response = requests.get(
'https://app.gethuntd.com/api/v1/public/sources',
headers={'X-API-Key': os.environ['HUNTD_API_KEY']}
)
sources = response.json()['sources']
print([s['source'] for s in sources]) # slugs to pass as ?source=
```
```json 200 theme={null}
{
"success": true,
"organization": "acme.com",
"totals": { "people": 92070, "companies": 3866 },
"sources": [
{
"source": "devin",
"label": "Devin",
"level": "user",
"people": 95276,
"users": 2637,
"userCompanies": 239,
"maintenance": false
}
]
}
```
```json 401 theme={null}
{
"success": false,
"error": {
"code": "INVALID_API_KEY",
"message": "API key is missing, invalid, or has been revoked."
}
}
```
```json 403 theme={null}
{
"success": false,
"error": {
"code": "ENDPOINT_NOT_ON_PLAN",
"message": "This endpoint is not available on your plan. Use POST /verify to check an address."
}
}
```
## Overview
Returns every source Huntd tracks for your organization, with counts. Not paginated: the list is
small. The `source` values are the slugs you pass as `?source=` to the other endpoints, and the ones
that appear in `sources` arrays on people and companies.
Pass a [date window](/public-api/conventions#date-filtering) to scope the counts, for example
`?discovered_days=30` for the last 30 UTC days.
## Reading the Counts
* **`people`** counts everyone we checked against the source. **`users`** counts the subset who are
confirmed users. The gap between them is expected, not an error.
* **Company-level sources** (`level: "company"`) are verified per account, not per person, so
`people` and `users` are `null`. Use `userCompanies` for those.
* **`maintenance: true`** means the source is paused and its counts read `0` until it's back.
## Errors
| HTTP | Error Code | Description |
| - | - | - |
| 400 | `INVALID_PARAMETER` | A date parameter is malformed, or both date styles were given |
| 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. |
| 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. |
## OpenAPI
````yaml api-reference/public-api.json GET /api/v1/public/sources
openapi: 3.0.3
info:
title: Huntd Public API
version: 1.0.0
description: >-
Read what Huntd tracks for your organization (enterprise plan), or check one
email address against the products you track (Agency plan).
contact:
name: Huntd Support
email: support@gethuntd.com
servers:
- url: https://app.gethuntd.com
description: Public API
security:
- ApiKeyAuth: []
tags:
- name: Public API
- name: Email Check
paths:
/api/v1/public/sources:
get:
tags:
- Public API
summary: List Sources
description: >-
The sources Huntd tracks for your organization, with counts. Not
paginated.
operationId: listSources
parameters:
- $ref: '#/components/parameters/discovered_days'
- $ref: '#/components/parameters/discovered_from'
- $ref: '#/components/parameters/discovered_to'
responses:
'200':
description: Sources and counts
content:
application/json:
schema:
$ref: '#/components/schemas/SourcesResponse'
example:
success: true
organization: acme.com
totals:
people: 92070
companies: 3866
sources:
- source: devin
label: Devin
level: user
people: 95276
users: 2637
userCompanies: 239
maintenance: false
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/ForbiddenPlan'
'429':
$ref: '#/components/responses/RateLimited'
'500':
$ref: '#/components/responses/InternalError'
'503':
$ref: '#/components/responses/PlanUnavailable'
components:
parameters:
discovered_days:
name: discovered_days
in: query
required: false
description: >-
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`.
schema:
type: integer
minimum: 1
maximum: 366
discovered_from:
name: discovered_from
in: query
required: false
description: Inclusive UTC start day, `YYYY-MM-DD`.
schema:
type: string
format: date
example: '2026-07-01'
discovered_to:
name: discovered_to
in: query
required: false
description: Inclusive UTC end day, `YYYY-MM-DD`.
schema:
type: string
format: date
example: '2026-07-31'
schemas:
SourcesResponse:
type: object
properties:
success:
type: boolean
enum:
- true
organization:
type: string
description: Your organization's domain.
example: acme.com
totals:
type: object
description: Organization-wide totals for the requested date window.
properties:
people:
type: integer
description: Total people checked.
companies:
type: integer
description: Total companies checked.
sources:
type: array
items:
$ref: '#/components/schemas/Source'
Source:
type: object
description: A source (product) Huntd tracks for your organization
properties:
source:
type: string
description: The slug to pass as `?source=` on other endpoints.
label:
type: string
description: Human-readable name, suitable for display.
level:
type: string
enum:
- user
- company
description: >-
`user`: verified per person. `company`: verified only at account
level.
people:
type: integer
nullable: true
description: >-
People checked against this source. `null` for a company-level
source.
users:
type: integer
nullable: true
description: >-
Of those checked, how many are confirmed users. `null` for a
company-level source.
userCompanies:
type: integer
nullable: true
description: Companies with at least one confirmed user of this source.
maintenance:
type: boolean
description: When `true`, the source is paused and its counts read `0`.
ApiError:
type: object
description: Every error uses this envelope. Branch on `error.code`, not the message.
properties:
success:
type: boolean
enum:
- false
error:
type: object
properties:
code:
type: string
enum:
- INVALID_PARAMETER
- INVALID_BODY
- INVALID_API_KEY
- ENDPOINT_NOT_ON_PLAN
- SOURCE_NOT_ALLOWED
- SUBSCRIPTION_INACTIVE
- JOB_NOT_FOUND
- SOURCE_NOT_VERIFIABLE
- SOURCE_UNAVAILABLE
- RATE_LIMITED
- RATE_LIMIT_EXCEEDED
- QUOTA_EXCEEDED
- STREAM_FAILED
- INTERNAL_ERROR
- ORG_KIND_UNAVAILABLE
message:
type: string
description: Human-readable. May change.
responses:
BadRequest:
description: A query parameter is malformed or out of range
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
examples:
limit:
summary: limit over 1000
value:
success: false
error:
code: INVALID_PARAMETER
message: '`limit` may not exceed 1000.'
dates:
summary: Both date styles given
value:
success: false
error:
code: INVALID_PARAMETER
message: >-
Use either `discovered_days` or
`discovered_from`/`discovered_to`, not both.
Unauthorized:
description: API key is missing, malformed, unknown or revoked
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
example:
success: false
error:
code: INVALID_API_KEY
message: API key is missing, invalid, or has been revoked.
ForbiddenPlan:
description: Not available on your plan, or no active subscription
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
examples:
notOnPlan:
summary: Not available on your plan
value:
success: false
error:
code: ENDPOINT_NOT_ON_PLAN
message: >-
This endpoint is not available on your plan. Use POST
/verify to check an address.
subscriptionInactive:
summary: Workspace has no active subscription
value:
success: false
error:
code: SUBSCRIPTION_INACTIVE
message: >-
This workspace doesn't have an active subscription. Please
contact your account manager to restore access.
RateLimited:
description: Over the API key's per-minute limit
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
example:
success: false
error:
code: RATE_LIMIT_EXCEEDED
message: Rate limit exceeded — 60 requests per minute. Retry in 23s.
headers:
Retry-After:
description: Seconds to wait before the next request.
schema:
type: integer
InternalError:
description: Internal error. Safe to retry.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
example:
success: false
error:
code: INTERNAL_ERROR
message: Internal server error.
PlanUnavailable:
description: Your plan briefly could not be confirmed. Retry.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
example:
success: false
error:
code: ORG_KIND_UNAVAILABLE
message: >-
Your organization's plan could not be checked. Please retry in a
moment.
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-API-Key
description: >-
API key in format: hntd_{id}_{secret}. Create one in Settings → API &
webhooks. `Authorization: Bearer` is also accepted.
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.