> ## 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"
}}>
    {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                                 |