> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryhuntr.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Make your first Huntr API call in minutes.

Get an API key, run a research request, and understand what comes back.

## 1. Get an API key

**Fastest path:** open the [Huntr dashboard](https://tryhuntr.com/dashboard), sign up, and copy your API key.

**API signup** (for programmatic onboarding):

```bash theme={null}
curl --request POST \
  --url https://api.tryhuntr.com/keys/create \
  --header 'content-type: application/json' \
  --data '{ "email": "you@company.com" }'
```

Click the verification link in your email. Your key is returned once — store it securely.

```bash theme={null}
export HUNTR_API_KEY="hntr_live_xxxxxxxxxxxx"
```

<Warning>
  Never put your API key in browser code, public repos, or client-side apps. Server-side and agent tooling only.
</Warning>

## 2. Check your balance

```bash theme={null}
curl https://api.tryhuntr.com/balance \
  -H "x-api-key: ${HUNTR_API_KEY}"
```

New accounts start with free credits (no card required). See [Credits and pricing](/concepts/credits-and-pricing) for how charges work.

## 3. Run your first research request

`POST /research` takes **one focused objective** and returns a synthesized answer. Start with `tier: "standard"` for company-level research.

```bash theme={null}
curl --request POST \
  --url https://api.tryhuntr.com/research \
  --header 'content-type: application/json' \
  --header "x-api-key: ${HUNTR_API_KEY}" \
  --data '{
    "prompt": "We sell cloud cost-optimization software to large enterprises. Research Shell'\''s IT and digital organization: who owns cloud infrastructure and FinOps decisions, initiatives announced from December 2024 through June 2026, and practical conversation angles tied to cost pressure.",
    "tier": "standard"
  }'
```

Example response:

```json theme={null}
{
  "success": true,
  "request_id": "req_example",
  "result": "Shell's current cloud-efficiency priorities include...",
  "data_source": "live",
  "tier": "standard",
  "model": "gemini-2.5-flash",
  "price": 0.027,
  "credits_remaining": 4.973
}
```

| Field         | Meaning                                                                                                          |
| ------------- | ---------------------------------------------------------------------------------------------------------------- |
| `result`      | The researched answer (string when no schema is provided)                                                        |
| `data_source` | `live` = grounded in retrieved data; `mixed` = retrieved + stable model knowledge; `model` = no usable retrieval |
| `price`       | USD charged for this request                                                                                     |
| `request_id`  | Use for logs and support                                                                                         |

## 4. Request structured output

When your workflow needs predictable top-level fields, pass a flat `schema` map. Keys become result fields; values describe what each field should contain.

```bash theme={null}
curl --request POST \
  --url https://api.tryhuntr.com/research \
  --header 'content-type: application/json' \
  --header "x-api-key: ${HUNTR_API_KEY}" \
  --data '{
    "prompt": "We provide fraud-prevention APIs for fintech platforms and are building an account plan for Stripe. Research enterprise product initiatives from June 2025 through June 2026, partnership angles for a fraud vendor, and deal risks.",
    "tier": "deep",
    "schema": {
      "summary": "Concise account summary",
      "recommended_angles": "Array of concrete partnership angles",
      "risks": "Array of risks that could stall the deal"
    }
  }'
```

The `schema` value is a **field map**, not JSON Schema. Nested schema definitions are not supported.

Structured responses include a `confidence` object per field (`live`, `model`, or `not_found`). Fields marked `not_found` are returned as `null`.

## 5. Try a direct endpoint

When you know exactly what you need, direct endpoints are faster and cheaper than `/research`.

Preview a company list size (free):

```bash theme={null}
curl --request POST \
  --url https://api.tryhuntr.com/company-search-count \
  --header 'content-type: application/json' \
  --header "x-api-key: ${HUNTR_API_KEY}" \
  --data '{
    "query": {
      "industry": { "include": ["Software Development"] },
      "location": { "include": ["US"] },
      "headcount": { ">": 50, "<": 500 }
    }
  }'
```

Find a work email for one person:

```bash theme={null}
curl --request POST \
  --url https://api.tryhuntr.com/person-email \
  --header 'content-type: application/json' \
  --header "x-api-key: ${HUNTR_API_KEY}" \
  --data '{
    "first_name": "Patrick",
    "last_name": "Collison",
    "company_domain": "stripe.com"
  }'
```

## What to read next

<CardGroup cols={2}>
  <Card title="Choose your workflow" icon="route" href="/concepts/choose-your-workflow">
    Decide between `/research` and direct endpoints before you build.
  </Card>

  <Card title="Company search" icon="building" href="/guides/company-search">
    Build ICP lists with structured filters and pagination.
  </Card>

  <Card title="Research agent" icon="file-magnifying-glass" href="/guides/research-agent">
    Write prompts that produce account-ready briefs.
  </Card>

  <Card title="Huntr MCP" icon="robot" href="/build-with-ai/huntr-mcp">
    Connect Huntr to Cursor, Claude, or Codex.
  </Card>
</CardGroup>