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

# Synchronous Grouped Query (Synthetic)

> Get aggregated counts (by court, class, area, status, phase, instance and party) of all lawsuits linked to a document on the Judit API — synchronous read ideal for dashboards and analytics.

export const EndpointBadges = ({auth = true, billing = "billable", flow = "sync", attachments = false, requiresVault = false}) => <div style={{
  marginTop: "-8px",
  marginBottom: "16px",
  display: "flex",
  flexWrap: "wrap",
  alignItems: "center",
  gap: "8px"
}}>
    {auth && <Badge color="gray">🔒 Requer api-key</Badge>}{" "}
    {billing === "billable" && <Badge color="yellow">💰 Cobrança por requisição</Badge>}{" "}
    {billing === "free" && <Badge color="green">✅ Grátis</Badge>}{" "}
    {billing === "on-demand" && <Badge color="purple">⚡ On-demand (preço diferenciado)</Badge>}{" "}
    {flow === "async" && <Badge color="blue">⏳ Assíncrono · webhook ou polling</Badge>}{" "}
    {flow === "sync" && <Badge color="green">⚡ Síncrono</Badge>}{" "}
    {attachments && <Badge color="purple">📎 Suporta with_attachments</Badge>}{" "}
    {requiresVault && <Badge color="red">🔑 Cofre de Credenciais</Badge>}
  </div>;

<Info>
  **New CNPJ format (IN 2229/24)**

  Judit already accepts the new **alphanumeric CNPJ** format in compliance with the [Brazilian Federal Revenue Normative Instruction No. 2229/2024](https://normasinternet2.receita.fazenda.gov.br/#/consulta/externa/141102).

  * **Zero effort:** no changes are required in your integration.
  * **Test environment:** use the document `A1B2C3D4/E5F6-68` to validate the flow and receive a mock lawsuit in response.
</Info>

The **Grouped (Synthetic) Query** delivers, in a single synchronous call, a statistical summary of every lawsuit linked to a document, grouped by class, subject, area, court, justice, phase, state, instance, party side and person type. Use it when the client needs a **bird's-eye view** rather than the full list.

> 🤖 Endpoint: `POST https://lawsuits.production.judit.io/lawsuits/synthetic`. Synchronous response with aggregated counts. To list each lawsuit, use `POST /lawsuits` ([Hot Storage](/en/cache-judit/hotstorage)). For a simple existence/count, use [`POST /lawsuits/count`](/en/api-reference/endpoint/crawler/req-count).

<EndpointBadges auth billing="billable" flow="sync" />

## When to use

<CardGroup cols={2}>
  <Card title="Executive dashboards" icon="chart-pie">
    Judicial-exposure panels: counts per court, phase, instance, area — without listing every lawsuit.
  </Card>

  <Card title="Quick risk analysis" icon="gauge-high">
    Onboarding or credit decisions: discover in milliseconds the judicial profile of a counterpart (civil vs. labor vs. tax).
  </Card>

  <Card title="Pre-segmentation" icon="layer-group">
    Before deciding between full or sample queries, see the size and distribution of the set.
  </Card>

  <Card title="Periodic reports" icon="calendar-days">
    Weekly/monthly reports aggregated by portfolio without trafficking large lawsuit volumes.
  </Card>
</CardGroup>

## Step 1: Create the Grouped Query (POST)

`POST https://lawsuits.production.judit.io/lawsuits/synthetic`

### Examples by document type

<CodeGroup>
  ```json By CPF theme={null}
  {
      "search": {
          "search_type": "cpf",
          "search_key": "999.999.999-99"
      }
  }
  ```

  ```json By CNPJ theme={null}
  {
      "search": {
          "search_type": "cnpj",
          "search_key": "99.999.999/9999-99"
      }
  }
  ```

  ```json By OAB theme={null}
  {
      "search": {
          "search_type": "oab",
          "search_key": "99999RJ"
      }
  }
  ```

  ```json By Name theme={null}
  {
      "search": {
          "search_type": "name",
          "search_key": "John Smith"
      }
  }
  ```
</CodeGroup>

### Payload parameters

| Parameter | Type | Required | Description |
| :- | :- | :- | :- |
| `search.search_type` | string | **Yes** | `"cpf"`, `"cnpj"`, `"oab"` or `"name"`. |
| `search.search_key` | string | **Yes** | Value to search. |
| `search.search_params.filter` | object | No | Structural filters — same shape as the [historical query](/en/requests/request-document#filtros-prévios-da-requisição-search_params-filter). |

### Examples with filters

<CodeGroup>
  ```json Passive side + amount theme={null}
  {
      "search": {
          "search_type": "cnpj",
          "search_key": "00.000.000/0001-00",
          "search_params": {
              "filter": {
                  "side": "Passive",
                  "tribunals": { "keys": ["TJSP","TRT2"], "not_equal": false },
                  "amount_gte": 50000
              }
          }
      }
  }
  ```

  ```json Distribution-date window theme={null}
  {
      "search": {
          "search_type": "cpf",
          "search_key": "999.999.999-99",
          "search_params": {
              "filter": {
                  "distribution_date_gte": "2024-01-01T00:00:00.000Z"
              }
          }
      }
  }
  ```

  ```json Exclude specific courts theme={null}
  {
      "search": {
          "search_type": "cnpj",
          "search_key": "00.000.000/0001-00",
          "search_params": {
              "filter": {
                  "tribunals": { "keys": ["TJSP"], "not_equal": true }
              }
          }
      }
  }
  ```
</CodeGroup>

### Request example (POST)

<CodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://lawsuits.production.judit.io/lawsuits/synthetic' \
    --header 'api-key: '"$JUDIT_API_KEY" \
    --header 'Content-Type: application/json' \
    --data '{
      "search": {
        "search_type": "cpf",
        "search_key": "999.999.999-99"
      }
    }'
  ```

  ```python Python theme={null}
  import os, requests

  resp = requests.post(
      "https://lawsuits.production.judit.io/lawsuits/synthetic",
      headers={
          "api-key": os.environ["JUDIT_API_KEY"],
          "Content-Type": "application/json",
      },
      json={"search": {"search_type": "cpf", "search_key": "999.999.999-99"}},
      timeout=15,
  )
  resp.raise_for_status()
  print(resp.json())
  ```

  ```javascript Node.js theme={null}
  const res = await fetch(
    "https://lawsuits.production.judit.io/lawsuits/synthetic",
    {
      method: "POST",
      headers: {
        "api-key": process.env.JUDIT_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        search: { search_type: "cpf", search_key: "999.999.999-99" },
      }),
    }
  );
  console.log(await res.json());
  ```

  ```go Go theme={null}
  package main

  import (
      "bytes"
      "encoding/json"
      "io"
      "net/http"
      "os"
  )

  func main() {
      body, _ := json.Marshal(map[string]any{
          "search": map[string]string{
              "search_type": "cpf",
              "search_key":  "999.999.999-99",
          },
      })
      req, _ := http.NewRequest("POST",
          "https://lawsuits.production.judit.io/lawsuits/synthetic",
          bytes.NewReader(body))
      req.Header.Set("api-key", os.Getenv("JUDIT_API_KEY"))
      req.Header.Set("Content-Type", "application/json")
      res, _ := http.DefaultClient.Do(req)
      defer res.Body.Close()
      out, _ := io.ReadAll(res.Body)
      println(string(out))
  }
  ```
</CodeGroup>

## Step 2: Read the response

The response is synchronous (HTTP 200) and aggregates the universe across multiple axes. `lawsuits_count` is the overall total; each axis is an array of `{ count, value }`.

| Axis | What it groups |
| :- | :- |
| `classifications` | Lawsuit classes (e.g. PROCEDIMENTO COMUM CÍVEL). |
| `subjects` | Lawsuit subjects (e.g. ACIDENTE DE TRÂNSITO). |
| `areas` | Areas of law (e.g. DIREITO CIVIL). |
| `tribunals` | Court acronyms (e.g. TJSP, TRT1). |
| `justices` | Branch (State, Federal, etc.). |
| `phases` | Current procedural phase. |
| `states` | State (UF) where the lawsuit runs. |
| `instances` | Instance (1 or 2). |
| `sides` | Side of the searched party (PASSIVE, ACTIVE, INTERESTED). |
| `person_types` | Party type (REQUERENTE, AUTOR, RÉU, etc.). |
| `lawsuits_count` | Overall total of lawsuits |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.