# Company search API: describe companies or set filters with Pubrio

Pubrio's company search API finds companies from a sentence that describes them, or from filters you set, up to 25 records per page. Each call is 1 credit, $0.01, and you pay per call through a 402 price quote. Send `POST https://agents.pubrio.com/zcj/qdnb07ya5fve/companies/search` with `query` or with filters, then read `metadata.filters` in the response to see what was searched.

## At a glance

- **Endpoint:** `POST https://agents.pubrio.com/zcj/qdnb07ya5fve/companies/search`
- **Body:** `query` (a plain-language description), or filters such as `locations`, `employees`, `keywords`, `revenues`, `founded_dates`, `technologies`, `verticals` and `places`, plus `per_page` and `page`
- **Price:** 1 credit per call, $0.01
- **Payment:** a 402 price quote, paid over x402 or MPP (wallet rails settling in USDC) and retried. No account or API key.
- **Response:** `metadata.filters` (the filters applied), `data.pagination` and `data.companies`, with a `domain_search_id` on each company
- **Limits:** at most 25 records per call. A larger `per_page` is rejected, not clamped.
- **Full purchase flow:** [the buyer skill](https://agents.pubrio.com/zcj/qdnb07ya5fve/SKILL.md)

## Search with a plain-language query

1. Send the description as `query`:

   ```bash
   curl -s -X POST https://agents.pubrio.com/zcj/qdnb07ya5fve/companies/search \
     -H 'Content-Type: application/json' \
     -d '{"query": "logistics software companies in Japan with 50 to 200 employees", "per_page": 5}'
   ```

   The storefront answers with a 402 that quotes the price. Nothing is charged until you pay it.

2. Pay the 402 with your x402 or MPP client and send the same request again with the payment attached. This example paid $0.01.

3. Read the response. This is an excerpt:

   ```json
   {
     "metadata": {
       "filters": {
         "query": "logistics software companies in Japan with 50 to 200 employees",
         "per_page": 5,
         "vertical_sub_categories": [43],
         "technologies": [14921364, "… 9 more"],
         "locations": ["JP"],
         "employees": [[50, 200]],
         "is_enable_similarity_search": true,
         "similarity_score": 0.65,
         "language": "en"
       },
       "ignored_fields": []
     },
     "data": {
       "pagination": {"page": 1, "per_page": 5, "total_entries": 41, "total_pages": 9, "is_estimated": false, "is_timeout": false},
       "companies": [
         {"company_name": "RAKSUL", "domain": "corp.raksul.com", "country_code": "JP", "company_size": 200, "industry": "Technology, Information And Internet", "domain_search_id": "<domain_search_id>"},
         "… 4 more"
       ]
     }
   }
   ```

The query became the location `JP`, the headcount range 50 to 200, one vertical sub-category by id and ten technologies by tag id, with similarity search on at a score of 0.65. It matched 41 companies. The first result was RAKSUL, listed in Technology, Information And Internet with a company size of 200. The matches are only as good as the interpretation, so check each company's `industry` against your description before you use the list.

## Check and refine the interpretation

`metadata.filters` is the search as it was run. Check it before you use the results. To refine the search, copy those filters into a new body without `query` and change the values you disagree with. Review these fields first:

| Field in `metadata.filters` | What it holds | How to refine |
| --- | --- | --- |
| `locations` | ISO 3166-1 alpha-2 headquarters codes | Add or remove codes |
| `employees` | Headcount ranges | Edit the range, or add more ranges |
| `vertical_sub_categories`, `verticals` | Industry ids | Replace the ids, or send free text with `is_enable_similarity_search` |
| `technologies` | Technology `tag_id`s | Drop the tags that don't fit, or add others |
| `similarity_score` | How closely free text must match an id | Raise it to match more strictly |
| `ignored_fields` | Body keys that were dropped | Must be empty. A misspelled filter widens the search instead of failing. |

## Search with filters set by hand

Send the filters directly:

```bash
curl -s -X POST https://agents.pubrio.com/zcj/qdnb07ya5fve/companies/search \
  -H 'Content-Type: application/json' \
  -d '{"locations": ["JP"], "employees": [[50, 200]], "keywords": ["logistics"], "per_page": 5}'
```

This request sets the same location and headcount that the query above was turned into, and uses the keyword `logistics` in place of the query. It paid $0.01. It matched 205 companies. The first result was ANA Cargo, with a company size of 84. A keyword matches companies described by that word, so `logistics` alone does not say software.

The two searches return different sets. The query's echo also holds a vertical sub-category and technologies by id, which this request does not set. To narrow the filter search the same way, add the `vertical_sub_categories` or `technologies` values from the query's echo.

| Filter | Takes |
| --- | --- |
| `locations` | `["JP"]`, ISO alpha-2 codes |
| `employees` | `[[50, 200]]`, one or more ranges |
| `keywords` | `["logistics"]` |
| `revenues` | `[min, max]` |
| `founded_dates` | `[2018, 2024]`, years |
| `technologies`, `verticals` | ids, or free text with `is_enable_similarity_search: true` |
| `places` | City or region names, such as `["Tokyo"]` |

Filter values are combined with OR by default. To require all of the listed values for keys such as `keywords` or `technologies`, add `filter_conditions` with `{"key": "keywords", "operator": "and"}`.

## Page, trim and reuse the results

- **Pagination:** `per_page` defaults to 25, which is also the maximum, and `page` starts at 1. Each page is a separate call at 1 credit. `total_entries` and `total_pages` show how many pages there are. When `is_estimated` is `true`, keep paging until a page returns fewer rows than `per_page`. When `is_timeout` is `true`, an empty page means the search didn't finish.
- **Payload:** a company record can carry `emails`, `phones` and `contacts` fields. Send `"exclude_fields": ["emails", "phones", "contacts"]` to drop them.
- **`domain_search_id`:** this is Pubrio's company id. Pass it in `companies` on another search to scope that search to those companies. The Lookup service returns the stored record for a company by its Pubrio id, at 1 credit ($0.01). Company Enrichment returns the record plus hiring, news, ad and similar-company signals for 3 credits, $0.03.

## Other searches

People, job posting, news, ad and cloud footprint searches cost 3 credits each, $0.03. The ad and cloud footprint searches are `POST https://agents.pubrio.com/zcj/qdnb07ya5fve/companies/advertisements/search` and `POST https://agents.pubrio.com/zcj/qdnb07ya5fve/companies/cloud_footprints/search`. The [Search API reference](https://agents.pubrio.com/zcj/qdnb07ya5fve/services/search/openapi.json) lists every search path. People search takes fields such as `people_titles`, `departments` and `people_locations`.

## Errors

| Response | Meaning | Action |
| --- | --- | --- |
| `402` | The price quote. Nothing is charged yet. | Pay and retry the same request, or stop |
| `416`, code `41613` | `per_page` is above the limit | Send 25 or fewer |
| `416` | `page` is past your plan's ceiling | Narrow the filters instead of paging further |
| `400` | Malformed body or invalid parameter | Read `code` and `message`, then fix the body |
| `429` | Rate limit exceeded | Wait and retry |

## Frequently asked questions

### Does Pubrio's company search API need an API key?

No. Each call is paid on its own through the 402 quote over x402 or MPP. You don't need an account. An agent identity is needed only for prepaid plans or the free trial.

### How much does a company search cost?

Each call is 1 credit, $0.01, whatever filters it uses. Card payment for a single call starts at $0.55, so a card buyer funds prepaid credit instead, such as Starter from $50. The free trial grants $1 of credit to an identity claimed with a verified email.

### How do I see how Pubrio understood my query?

Read `metadata.filters` in the response. It lists the locations, headcount, industry ids, technology ids and similarity settings that were searched. Copy them into a filter body to refine the search.

### Can I get more than 25 companies per call?

No. 25 is the maximum `per_page`. Request further pages with `page`, at 1 credit each.

### Is the query or the filters better for building a company list?

Start with `query` to get a set of filters quickly. Then send the filters by hand, so you control exactly which values the list depends on.

## Keep reading

- [The buyer skill](https://agents.pubrio.com/zcj/qdnb07ya5fve/SKILL.md): the full purchase flow
- [How to pay](https://agents.pubrio.com/zcj/qdnb07ya5fve/payment.md): rails, credits and the free trial
- [Search service and prices](https://agents.pubrio.com/zcj/qdnb07ya5fve/services/search)
- [Error reference](https://agents.pubrio.com/zcj/qdnb07ya5fve/errors.md)

---

Updated 2026-11-04. All Pubrio guides: https://agents.pubrio.com/guides.md. Storefront: https://agents.pubrio.com/zcj/qdnb07ya5fve/llms.txt.