---
title: "GET /v1/cnpjs"
description: "Buscar empresas por filtros"
canonical: "https://cnpj.ia.br/docs/referencia/search-cnpjs"
date_modified: 2026-09-02
source: "cnpj.ia.br"
---

docs · base agosto/2026 Atualizado em 02/09/2026

# GET /v1/cnpjs

Buscar empresas por filtros

Página de até 20 empresas com campos `basic`, ordenação fixa por CNPJ, paginação por cursor. Custa 1 crédito por empresa retornada; página vazia não custa. Não disponível no plano Free.

## Créditos

por empresa retornada · **1** crédito página máx. · **20** empresas

## Parâmetros

| Nome | Em | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- | --- |
| `uf` | query | `string` | — | Sigla da UF. |
| `municipio` | query | `string` | — | Código IBGE do município (7 dígitos). |
| `cnae` | query | `string` | — | CNAE fiscal, 7 dígitos ou prefixo (classe, grupo, divisão). |
| `porte` | query | `string` enum: `ME`, `EPP`, `DEMAIS` | — | — |
| `situacao` | query | `string` enum: `ATIVA`, `SUSPENSA`, `INAPTA`, `BAIXADA`, `NULA` | — | — |
| `simples` | query | `boolean` | — | — |
| `mei` | query | `boolean` | — | — |
| `natureza` | query | `string` | — | Código da natureza jurídica. |
| `capital_min` | query | `number` mín. 0 | — | — |
| `capital_max` | query | `number` mín. 0 | — | — |
| `abertura_de` | query | `string` formato: `date` | — | — |
| `abertura_ate` | query | `string` formato: `date` | — | — |
| `cursor` | query | `string` | — | Cursor opaco da página anterior (`meta.next_cursor`). |

## Respostas

### 200 OK

Página de resultados.

| Header | Tipo | Descrição |
| --- | --- | --- |
| `X-Request-Id` | `string` | Identificador da requisição para suporte. |
| `X-Credits-Charged` | `integer` | Créditos debitados nesta resposta. |
| `X-Credits-Remaining` | `integer` | Créditos restantes (franquia + pacotes). |
| `X-Credits-Reset` | `string` formato: `date-time` | Instante do próximo reset da franquia (RFC 3339). |
| `X-RateLimit-Limit` | `integer` | Requisições por minuto do plano (por conta). |
| `X-RateLimit-Remaining` | `integer` | Requisições restantes no minuto corrente. |

### 400 Requisição inválida

Filtro desconhecido ou valor fora do enum.

### 401 Não autorizado

Chave ausente, desconhecida, revogada ou expirada.

### 402 Pagamento necessário

Franquia e pacotes esgotados. Header X-Credits-Reset.

### 403 Proibido

`insufficient_plan` (operação fora do plano) ou `payment_required` (cobrança recusada há mais de 7 dias).

### 429 Excesso de requisições

Requisições por minuto da conta excedidas. Header Retry-After.

| Header | Tipo | Descrição |
| --- | --- | --- |
| `Retry-After` | `integer` | Só em 429 e 503: segundos até tentar de novo. |

### 503 Serviço indisponível

Janela mensal de atualização da base. Header Retry-After.

### 504 Tempo esgotado

Timeout de consulta. `retryable: true`; nada é cobrado.

## Ferramenta MCP

No servidor MCP oficial esta operação é a ferramenta `buscar_empresas`, com a mesma chave e os mesmos créditos da API.

## Exemplo

```bash
curl -s "https://api.cnpj.ia.br/v1/cnpjs" \
  -H "Authorization: Bearer $CNPJIA_KEY"
```