# Size a market with BlitzAPI's TAM API by headcount or hiring

BlitzAPI's Company Search sizes a total addressable market in two ways. `POST https://agents.blitz-api.ai/zcj/2l71lk8rh8ju/v2/company/tam-by-people` returns the companies that employ people in matching roles, and `POST https://agents.blitz-api.ai/zcj/2l71lk8rh8ju/v2/company/tam-by-jobs` returns the companies hiring for those roles. Each company returned costs $0.001, drawn from prepaid Credits, and you resend the request with the returned `cursor` until it is `null`.

## At a glance

- **Endpoints:** `POST https://agents.blitz-api.ai/zcj/2l71lk8rh8ju/v2/company/tam-by-people` (headcount) and `POST https://agents.blitz-api.ai/zcj/2l71lk8rh8ju/v2/company/tam-by-jobs` (hiring)
- **Body:** `people` or `job` filters, `company` filters, `max_results` (1 to 50, default 3) and `cursor`
- **Price:** $0.001. A page that returns no companies costs nothing.
- **Payment:** prepaid Credits, paid by card through a hosted checkout or a shared payment token. A card purchase starts at $0.60.
- **Access:** `Authorization: Bearer <token>`, the agent credential the storefront issues. You need no BlitzAPI account or API key.
- **Response:** `results[]` (each a `company` profile with `matched_people` or `matched_jobs`), `results_length`, `max_results` and `cursor`
- **Limits:** up to 50 companies per page. `min_per_company` goes up to 25.
- **Full purchase flow:** [the buyer skill](https://agents.blitz-api.ai/zcj/2l71lk8rh8ju/SKILL.md)

## Choose headcount or hiring

| The market is | Endpoint | Count on each company |
| --- | --- | --- |
| Companies that already employ people in a role | `/v2/company/tam-by-people` | `matched_people`: current employees who match |
| Companies hiring for a role now | `/v2/company/tam-by-jobs` | `matched_jobs`: matching postings |

Both endpoints return distinct companies, so each company appears once per query. Both take company filters and bill the same companies meter.

## Count companies by role

1. Get a free agent credential and buy Credits once by card, from $0.60. [The buyer skill](https://agents.blitz-api.ai/zcj/2l71lk8rh8ju/SKILL.md) has the steps; calls then draw on the balance with the credential as a bearer token.

2. Send the first page with your role and company filters:

   ```bash
   curl -s https://agents.blitz-api.ai/zcj/2l71lk8rh8ju/v2/company/tam-by-people \
     -H "Authorization: Bearer $ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"people": {"job_title": {"include": ["Data Engineer"], "exclude": []}}, "company": {"hq": {"country_code": ["US"]}}, "max_results": 3}'
   ```

3. Read the page. This example returned three US companies, each with its profile and a `matched_people` count, plus a `cursor` for the next page:

   ```json
   {
     "results": [
       {
         "company": {
           "name": "CBRE Global Workplace Solutions (GWS)",
           "industry": "Real Estate",
           "type": "Public Company",
           "size": "10001+",
           "employees_on_linkedin": 20991,
           "hq": {"city": "Dallas", "state": "Texas", "country_code": "US", "region": "NORAM"},
           "domain": "cbre.com"
         },
         "matched_people": 75
       },
       "… 2 more"
     ],
     "results_length": 3,
     "max_results": 3,
     "cursor": "<cursor>"
   }
   ```

   The three companies drew $0.003 from prepaid credit, as reported in the response's `zc-billing` header. The example call answered in 1.0 seconds.

4. Resend the same body with `"cursor": "<cursor>"` set to the returned value.
5. Stop when `cursor` is `null`. The market size is the sum of `results_length` across all pages.

For a full count, set `max_results` to 50 on the first page so the market needs fewer pages.

## Count companies hiring for a role

Send the job filters under `job`. Set `job.min_per_company` to keep only companies with at least that many matching postings:

```bash
curl -s https://agents.blitz-api.ai/zcj/2l71lk8rh8ju/v2/company/tam-by-jobs \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"job": {"title": {"include": ["Data Engineer"]}, "location": {"country_code": {"include": ["US"]}}, "date_posted": {"last_days": 30}, "min_per_company": 2}, "company": {"is_agency": false}, "max_results": 50}'
```

Each result carries a `company` profile and `matched_jobs`. Page through the results with `cursor` the same way as for headcount.

## Narrow the market

| To count | Set |
| --- | --- |
| A role by keyword | `people.job_title.include` or `job.title.include` |
| An exact title only | Wrap the value in square brackets, for example `"[Data Engineer]"` |
| A function | `people.job_function`, such as `["Engineering"]` or `["Information Technology"]` |
| A level | `people.job_level`: `C-Team`, `Director`, `Manager`, `Staff`, `VP` or `Other` |
| Companies with several matches | `people.min_per_company` or `job.min_per_company`, 0 to 25 |
| Recent postings | `job.date_posted.last_days` |
| Required experience | `job.seniority.include`: `0-2`, `2-5`, `5-10` or `10+` |
| Headquarters country | `company.hq.country_code`: an array on TAM by People, `{"include": [...]}` on TAM by Jobs |
| No staffing agencies | `company.is_agency: false` on TAM by Jobs |

## Budget and limits

- Every company returned is billed. A market of 1,000 companies costs $1, and a market of 10,000 costs $10.
- A page with no companies costs nothing. A request rejected with 422 does not run and uses no records.
- When `min_per_company` filters heavily, a page can hold fewer companies than `max_results`. Keep paging until `cursor` is `null`.
- The response lists companies and counts, not the people or the postings behind the counts.
- Each paid response's `zc-billing` header reports `chargedUsd` and `remainingCreditUsd`, so you can stop paging before credit runs out.

## Errors

| Response | Meaning | Action |
| --- | --- | --- |
| `401 bearer_required` | The call had no agent credential | Register one at [auth.md](https://agents.blitz-api.ai/zcj/2l71lk8rh8ju/auth.md), then retry with the bearer |
| `403 plan_required` | The credential holds no plan that covers the call | Buy Credits through the plan listed in the body, then retry |
| `usage_exhausted` | Prepaid credit ran out | Top up with `POST https://agents.blitz-api.ai/zcj/2l71lk8rh8ju/extend` and `{"amountUsd": "..."}` |
| `422` | Unknown field or invalid value | Fix the field named in `errors[].field`. Nothing ran. |
| `429` | Rate limit exceeded | Wait, then retry the same page |
| `400` | The body is not valid JSON | Send a JSON object with `Content-Type: application/json` |

## Frequently asked questions

### Is there an API that counts companies by role?

Yes. TAM by People returns every distinct company with current employees who match your title, function, level and location filters, inside the company filters you set. Each company comes with its `matched_people` count.

### How much does it cost to size a market?

You pay $0.001 for each company returned, so the full count costs the number of companies times that price. A page that returns no companies is free. Credits start at $0.50, and a card purchase starts at $0.60.

### Can I find the companies hiring for a role?

Yes. TAM by Jobs returns the companies with matching job postings, each with `matched_jobs`. You can filter by job title, job location, posting date and seniority. Set `job.min_per_company` to keep only companies hiring at volume.

### Do I need a BlitzAPI account or API key?

No. You register a free agent credential with the storefront, buy Credits by card and call the API with `Authorization: Bearer <token>`.

### How do I know the count is complete?

The count is complete when a response returns `cursor` as `null`. Until then, resend the same filters with the returned cursor and add up `results_length` from each page.

## Keep reading

- [Buyer skill](https://agents.blitz-api.ai/zcj/2l71lk8rh8ju/SKILL.md): the credential, Credits and recovery flow
- [How to pay](https://agents.blitz-api.ai/zcj/2l71lk8rh8ju/payment.md): Credits, card checkout and top-ups
- [Company Search API reference](https://agents.blitz-api.ai/zcj/2l71lk8rh8ju/services/company-search/openapi.json): every filter and field
- [Error reference](https://agents.blitz-api.ai/zcj/2l71lk8rh8ju/errors.md): every error code and how to react
- [Catalog](https://agents.blitz-api.ai/zcj/2l71lk8rh8ju/manifest.json): live prices and plans

---

Updated 2026-10-22. All BlitzAPI guides: https://agents.blitz-api.ai/guides.md. Storefront: https://agents.blitz-api.ai/zcj/2l71lk8rh8ju/llms.txt.