Asynchronous Lawsuit Query by CNJ

Cached response (cached_response)When you create a lawsuit or historical query, Judit first checks whether the data already exists in our database. If it does, we return the result immediately — both in the API response and via webhook (if registered) — with the field cached_response: true.In parallel, Judit triggers a fresh fetch against the courts. If anything has changed, you receive a second response with cached_response: false. That is the most up-to-date result.This is why it is normal to receive two seemingly identical webhooks for the same request_id:

The first one comes from cache (cached_response: true)
The last one is the updated result (cached_response: false)

Use this field to reliably identify which response represents the most recent state of the lawsuit.

One court fetch per day, per lawsuitFor lawsuit queries (search_type: "lawsuit_cnj"), fetching updated data from the court for a specific lawsuit happens, by default, at most once per day. If you trigger more than one query for the same lawsuit on the same day, the following calls return the data already in cache (cached_response: true), with no new court fetch.This is a performance optimization, not a billing exemption: every request you send is counted and billed normally, as established in your contract, regardless of whether the result came from cache or from a fresh court extraction.

The Asynchronous Lawsuit Query is the most complete and freshest way to fetch a lawsuit: Judit reaches the court in real time, downloads the full tree (cover, parties, lawyers, steps, classes, attachments) and returns it via webhook or polling.

🤖 The lawsuit search route operates asynchronously. The client application must make a POST /requests to start the search, wait for processing (via Webhook or by polling GET /requests/{id}), and, when the status is completed, capture the data via GET /responses.

When to use

Forced refresh

The lawsuit must reflect the latest court state — the datalake cache isn’t enough.

Full cover + steps

You need every cover field, all steps, attachments (up to 1,000 per query) and relationships.

AI summary

Trigger judit_ia: ["summary"] to get a human-friendly summary ready for your UI.

Lawsuits under secrecy

Combine with the Credentials Vault to reach lawsuits that require court login.

If speed beats freshness (e.g. on-screen validation, interactive dashboard), use the Hot Storage Synchronous Query — millisecond response from Judit’s datalake. If you want a single synchronous call with a freshness guarantee at the court (no polling or webhook to manage), see the On-Demand Query.

Asynchronous on-demand flow (overview)

Understanding the Asynchronous Flow

Since data extraction directly from the courts can take a few seconds or minutes (depending on court instability), the Judit API uses an asynchronous request pattern. The flow consists of 3 simple steps:

Create the request: You send the lawsuit number.
Track the status: You check if the bot has finished the extraction.
Capture the result: You consume the JSON with the lawsuit data.

Step 1: Creating the Search Request

To initiate a lawsuit search, make a POST request to the base requests route, sending the desired parameters in the body of the call.

Payload Parameters (Body)

Refer to the table below to configure your search, enable attachments, or trigger Judit AI:

Parameter	Type	Required	Description
`search.search_type`	string	Yes	Defines the entity being searched. For lawsuits, always use `"lawsuit_cnj"`.
`search.search_key`	string	Yes	The lawsuit number in the CNJ standard (e.g., `"0009999-99.9999.8.26.9999"`).
`with_attachments`	boolean	No	If `true`, Judit will download the lawsuit files, up to 1,000 attachments per request. Read How attachments work before using it.
`judit_ia`	array	No	List of AI features applied to the result. Send `["summary"]` to receive a humanized summary of the header and case updates.
`search_params.lawsuit_instance`	integer	No	Forces the search at a specific instance (e.g., `1` or `2`).
`search_params.should_search_superior_instances`	boolean	No	If `true`, Judit runs a complementary search on the Superior Instance systems (STF, STJ, TST and CNJ). Adds +30% over the standard price of the request — see Searching Superior Instances.

Judit AI (Beta): The artificial intelligence feature (judit_ia) is in Beta. Response time may vary and the summary structure is subject to improvements.

Searching Superior Instances

By default, the lawsuit search considers the lawsuit sent in the request and the instances normally associated with that query.

When to enable it

When the lawsuit you send originates in the 1st or 2nd instance and you want Judit to also run a complementary search on the Superior Instance systems — STF, STJ, TST and CNJ — send should_search_superior_instances: true inside search_params:

curl --location 'https://requests.production.judit.io/requests/' \
--header 'Content-Type: application/json' \
--header 'api-key: <api-key>' \
--data '{
    "search": {
        "search_type": "lawsuit_cnj",
        "search_key": "0045869-06.2009.4.01.0000",
        "search_params": {
            "should_search_superior_instances": true
        }
    }
}'

Request cost

Enabling this option adds 30% over the standard price of the request, due to the extra processing required to query the Superior Instance systems. Whether the surcharge applies depends on the origin of the lawsuit you send:

Scenario	Billing
CNJ from the 1st or 2nd instance, with `should_search_superior_instances: true`	Standard price +30%
CNJ that already corresponds to a lawsuit originating in a Superior Instance	Standard product price, without the 30% surcharge
Request without the parameter (default behavior)	Standard price

In other words: if the number you send already belongs to a lawsuit originating in a Superior Instance, the query is billed at the normal price even when the parameter is sent. The surcharge only applies when the complementary search on the superior systems actually happens.

When related lawsuits in other instances are identified, their numbers may be returned in the query result. What comes back is the reference — the related lawsuit’s number — not its full data. To obtain the header, case updates and remaining information of a related lawsuit, you must make a new request for each lawsuit you want, using the returned number as the search_key.

Each of those queries for related lawsuits is a new lawsuit search and is billed as such.

Request Example (POST)

curl --location 'https://requests.production.judit.io/requests/' \
--header 'Content-Type: application/json' \
--header 'api-key: <api-key>' \
--data '{
    "search": {
        "search_type": "lawsuit_cnj",
        "search_key": "0009999-99.9999.8.26.9999"
    },
    "with_attachments": false
}'

curl --location 'https://requests.production.judit.io/requests/' \
--header 'Content-Type: application/json' \
--header 'api-key: <api-key>' \
--data '{
    "search": {
        "search_type": "lawsuit_cnj",
        "search_key": "0009999-99.9999.8.26.9999"
    },
    "with_attachments": true
}'

curl --location 'https://requests.production.judit.io/requests/' \
--header 'Content-Type: application/json' \
--header 'api-key: <api-key>' \
--data '{
    "search": {
        "search_type": "lawsuit_cnj",
        "search_key": "0009999-99.9999.8.26.9999"
    },
    "with_attachments": true,
    "judit_ia": ["summary"]
}'

curl --location 'https://requests.production.judit.io/requests/' \
--header 'Content-Type: application/json' \
--header 'api-key: <api-key>' \
--data '{
    "search": {
        "search_type": "lawsuit_cnj",
        "search_key": "0045869-06.2009.4.01.0000",
        "search_params": {
            "should_search_superior_instances": true
        }
    },
    "with_attachments": true
}'

{
    "request_id": "84b4d8f5-50f8-4c14-818f-912c722a6908",
    "search": {
        "search_type": "lawsuit_cnj",
        "search_key": "0009999-99.9999.8.26.9999",
        "response_type": "lawsuit"
    },
    "with_attachments": true,
    "status": "pending",
    "created_at": "2024-06-18T22:03:35.560Z"
}

Save the value of request_id, as you will need it for the next steps.

🚀 Shortcut: Automate with Webhooks (Recommended)If you have a Webhook URL configured, Steps 2 and 3 below are entirely optional. Instead of programming your application to keep polling the request status, the Judit API will send the found lawsuits incrementally directly to your server as soon as they are captured, finishing the flow with a request_completed event.👉 Learn how to configure and receive Webhooks here

Step 2: Check the Request Status

This step is crucial if you are not using Webhooks. Responses are inserted into the database incrementally as the bots interact with the court.

To find out whether the extraction has finished, query the request history endpoint passing the ID generated in Step 1:

curl --location 'https://requests.production.judit.io/requests/<request_id>' \
--header 'api-key: <api-key>' \
--header 'Content-Type: application/json' \
--data ''

{
  "request_id": "05ee9825-b2b4-480b-b29e-f071ca7d9c72",
  "search": {
      "search_type": "lawsuit_cnj",
      "search_key": "9999999-99.9999.9.99.9999",
      "response_type": "lawsuit",
      "search_params": {
        "filter": {},
        "pagination": {}
      }
  },
  "origin": "api",
  "origin_id": "46fac09a-b34f-4dfd-a24f-b358bf04dfd4",
  "user_id": "82082593-c664-4d7b-b174-2f0dc4791daf",
  "status": "completed",
  "created_at": "2024-02-21T17:33:22.876Z",
  "updated_at": "2024-02-21T17:33:26.316Z",
  "tags": {
      "dashboard_id": null
  }
}

Wait until the status property changes to "completed".

Step 3: Capture the Result (The Lawsuit)

As soon as the status is completed, you can retrieve the complete lawsuit data (and the AI summary, if requested).

Request example (GET)

curl --location 'https://requests.production.judit.io/responses?page_size=100&request_id=<request_id>' \
  --header 'api-key: '"$JUDIT_API_KEY"

const res = await fetch(
  `https://requests.production.judit.io/responses?page_size=100&request_id=${requestId}`,
  { headers: { "api-key": process.env.JUDIT_API_KEY } }
);
const data = await res.json();
console.log(data.page_data);

<?php
$ch = curl_init('https://requests.production.judit.io/responses?page_size=100&request_id=' . urlencode($requestId));
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['api-key: ' . getenv('JUDIT_API_KEY')],
]);
echo curl_exec($ch);

import os, requests

resp = requests.get(
    "https://requests.production.judit.io/responses",
    params={"request_id": request_id, "page_size": 100},
    headers={"api-key": os.environ["JUDIT_API_KEY"]},
    timeout=15,
)
print(resp.json())

package main

import (
    "fmt"
    "io"
    "net/http"
    "net/url"
    "os"
)

func main() {
    requestID := "<request_id>"
    base, _ := url.Parse("https://requests.production.judit.io/responses")
    q := base.Query(); q.Set("request_id", requestID); q.Set("page_size", "100")
    base.RawQuery = q.Encode()
    req, _ := http.NewRequest("GET", base.String(), nil)
    req.Header.Set("api-key", os.Getenv("JUDIT_API_KEY"))
    res, _ := http.DefaultClient.Do(req)
    defer res.Body.Close()
    out, _ := io.ReadAll(res.Body); fmt.Println(string(out))
}

Response examples

See response examples (3 variants)

{
        "request_status": "completed",
        "page": 1,
        "page_count": 1,
        "all_pages_count": 1,
        "all_count": 1,
        "page_data": [
            {
                "request_id": "03abbf28-822e-45a0-a22c-098fbe157aa4",
                "response_id": "061c60b2-7fa9-4d20-87bb-1bedd31d5572",
                "origin": "api",
                "origin_id": "03abbf28-822e-45a0-a22c-098fbe157aa4",
                "response_type": "lawsuit",
                "response_data": {
                    "code": "9999999-99.9999.9.99.9999",
                    "justice": "8",
                    "tribunal": "26",
                    "instance": 1,
                    "distribution_date": "2019-02-15T16:00:00.000Z",
                    "judge": "Usuário teste",
                    "tribunal_acronym": "TJSP",
                    "secrecy_level": 0,
                    "tags": {
                        "crawl_id": "a9b6820a-6c84-4db5-b4f4-2f1909aa3805",
                        "dictionary_updated_at": "2025-08-13T18:43:48.143Z"
                    },
                    "subjects": [
                        {
                            "code": "",
                            "name": "PAGAMENTO"
                        }
                    ],
                    "classifications": [
                        {
                            "code": "7",
                            "name": "PROCEDIMENTO COMUM CÍVEL"
                        }
                    ],
                    "courts": [
                        {
                            "name": "1ª Vara Cível"
                        }
                    ],
                    "parties": [
                        {
                            "main_document": "99999999999",
                            "name": "Usuário 2",
                            "side": "Passive",
                            "person_type": "Desconhecido",
                            "documents": [
                                {
                                    "document": "99999999999",
                                    "document_type": "cpf"
                                }
                            ],
                            "lawyers": [
                                {
                                    "name": "Usuário 3",
                                    "documents": []
                                }
                            ]
                        },
                        {
                            "main_document": "99999999999",
                            "name": "Usuário 4",
                            "side": "Active",
                            "person_type": "Desconhecido",
                            "documents": [
                                {
                                    "document": "99999999999",
                                    "document_type": "cnpj"
                                }
                            ],
                            "lawyers": [
                                {
                                    "name": "Usuário 5",
                                    "documents": []
                                }
                            ]
                        },
                        {
                            "name": "Usuário 4",
                            "side": "Active",
                            "person_type": "Desconhecido",
                            "documents": [],
                            "lawyers": [
                                {
                                    "name": "Usuário 5",
                                    "documents": []
                                }
                            ]
                        },
                        {
                            "name": "Usuário 2",
                            "side": "Passive",
                            "person_type": "Desconhecido",
                            "documents": [],
                            "lawyers": [
                                {
                                    "name": "Usuário 3",
                                    "documents": []
                                }
                            ]
                        },
                        {
                            "name": "Usuário 5",
                            "side": "Active",
                            "person_type": "Advogado",
                            "documents": []
                        },
                        {
                            "name": "Usuário 3",
                            "side": "Passive",
                            "person_type": "Advogado",
                            "documents": []
                        }
                    ],
                    "steps": [
                        {
                            "lawsuit_cnj": "9999999-99.9999.9.99.9999",
                            "lawsuit_instance": 1,
                            "step_date": "2019-07-16T00:00:00.000Z",
                            "private": false,
                            "tags": {
                                "crawl_id": "36fc0ffd-98fa-4990-bd6f-6a82e5565119"
                            },
                            "step_id": "56174b2e",
                            "content": "Início da Execução Juntado\n0003695-16.2019.8.26.0189 - Cumprimento de sentença",
                            "steps_count": 32,
                            "created_at": "2025-07-09T13:48:33.114Z",
                            "updated_at": "2025-08-11T18:57:39.041Z"
                        },
                        {
                            "lawsuit_cnj": "9999999-99.9999.9.99.9999",
                            "lawsuit_instance": 1,
                            "step_date": "2019-06-06T00:00:00.000Z",
                            "private": false,
                            "tags": {
                                "crawl_id": "36fc0ffd-98fa-4990-bd6f-6a82e5565119"
                            },
                            "step_id": "939794b9",
                            "content": "Arquivado Definitivamente",
                            "created_at": "2025-07-09T13:48:33.114Z",
                            "updated_at": "2025-08-11T18:57:39.041Z"
                        },
                        {
                            "lawsuit_cnj": "9999999-99.9999.9.99.9999",
                            "lawsuit_instance": 1,
                            "step_date": "2019-06-06T00:00:00.000Z",
                            "private": false,
                            "tags": {
                                "crawl_id": "36fc0ffd-98fa-4990-bd6f-6a82e5565119"
                            },
                            "step_id": "423978eb",
                            "content": "Trânsito em Julgado às partes\nCertidão de trânsito em julgado e remessa ao arquivo geral",
                            "created_at": "2025-07-09T13:48:33.114Z",
                            "updated_at": "2025-08-11T18:57:39.041Z"
                        }
                    ],
                    "attachments": [
                        {
                            "attachment_id": "60153051-1-1",
                            "attachment_date": "2019-02-15T16:00:41.000Z",
                            "attachment_name": "Petição (Outras)",
                            "extension": "pdf",
                            "status": "pending",
                            "tags": {
                                "crawl_id": "424cd251-3d1f-407e-9d17-cb61219545aa"
                            },
                            "user_data": null
                        },
                        {
                            "attachment_id": "60153057-5-1",
                            "attachment_date": "2019-02-15T16:00:42.000Z",
                            "attachment_name": "Instrumento de Procuração",
                            "extension": "pdf",
                            "status": "pending",
                            "tags": {
                                "crawl_id": "424cd251-3d1f-407e-9d17-cb61219545aa"
                            },
                            "user_data": null
                        },
                        {
                            "attachment_id": "60153061-6-1",
                            "attachment_date": "2019-02-15T16:00:43.000Z",
                            "attachment_name": "Guia",
                            "extension": "pdf",
                            "status": "pending",
                            "tags": {
                                "crawl_id": "424cd251-3d1f-407e-9d17-cb61219545aa"
                            },
                            "user_data": null
                        },
                        {
                            "attachment_id": "60153064-7-1",
                            "attachment_date": "2019-02-15T16:00:44.000Z",
                            "attachment_name": "Guia",
                            "extension": "pdf",
                            "status": "pending",
                            "tags": {
                                "crawl_id": "424cd251-3d1f-407e-9d17-cb61219545aa"
                            },
                            "user_data": null
                        }
                    ],
                    "related_lawsuits": [],
                    "crawler": {
                        "source_name": "JSaj - TJ - SP - Lawsuit - Auth - 1 instance",
                        "crawl_id": "a9b6820a-6c84-4db5-b4f4-2f1909aa3805",
                        "weight": 10,
                        "updated_at": "2025-08-13T18:43:47.770Z"
                    },
                    "metadata": {},
                    "county": "VARA JUIZADO ESP. CIVEL CRIM. DE FERNANDOPOLIS",
                    "amount": 5798,
                    "state": "SP",
                    "city": "FERNANDOPOLIS",
                    "justice_description": "JUSTIÇA ESTADUAL",
                    "last_step": {
                        "lawsuit_cnj": "9999999-99.9999.9.99.9999",
                        "lawsuit_instance": 1,
                        "step_date": "2019-07-16T00:00:00.000Z",
                        "private": false,
                        "tags": {
                            "crawl_id": "a9b6820a-6c84-4db5-b4f4-2f1909aa3805"
                        },
                        "step_id": "56174b2e",
                        "content": "Início da Execução Juntado\n0003695-16.2019.8.26.0189 - Cumprimento de sentença",
                        "steps_count": 32
                    },
                    "phase": "Execução ou cumprimento",
                    "status": "Ativo",
                    "name": "Usuário 4 X Usuário 2",
                    "created_at": "2025-08-13T18:43:51.016Z",
                    "updated_at": "2025-08-13T18:43:51.016Z",
                    "free_justice": false
                },
                "user_id": "7f8065a3-4891-428d-9456-dedfc12ff850",
                "created_at": "2025-08-13T18:40:54.982Z",
                "request_created_at": "2025-08-13T18:40:54.037Z",
                "tags": {
                    "debug": true,
                    "dashboard_id": null,
                    "cached_response": false,
                    "cached": false
                }
            }
        ]
    }

{
        "request_status": "completed",
        "page": 1,
        "page_count": 1,
        "all_pages_count": 1,
        "all_count": 1,
        "page_data": [
            {
                "request_id": "03abbf28-822e-45a0-a22c-098fbe157aa4",
                "response_id": "061c60b2-7fa9-4d20-87bb-1bedd31d5572",
                "origin": "api",
                "origin_id": "03abbf28-822e-45a0-a22c-098fbe157aa4",
                "response_type": "lawsuit",
                "response_data": {
                    "code": "9999999-99.9999.9.99.9999",
                    "justice": "8",
                    "tribunal": "26",
                    "instance": 1,
                    "distribution_date": "2019-02-15T16:00:00.000Z",
                    "judge": "Usuário teste",
                    "tribunal_acronym": "TJSP",
                    "secrecy_level": 0,
                    "tags": {
                        "crawl_id": "a9b6820a-6c84-4db5-b4f4-2f1909aa3805",
                        "dictionary_updated_at": "2025-08-13T18:43:48.143Z"
                    },
                    "subjects": [
                        {
                            "code": "",
                            "name": "PAGAMENTO"
                        }
                    ],
                    "classifications": [
                        {
                            "code": "7",
                            "name": "PROCEDIMENTO COMUM CÍVEL"
                        }
                    ],
                    "courts": [
                        {
                            "name": "1ª Vara Cível"
                        }
                    ],
                    "parties": [
                        {
                            "main_document": "99999999999",
                            "name": "Usuário 2",
                            "side": "Passive",
                            "person_type": "Desconhecido",
                            "documents": [
                                {
                                    "document": "99999999999",
                                    "document_type": "cpf"
                                }
                            ],
                            "lawyers": [
                                {
                                    "name": "Usuário 3",
                                    "documents": []
                                }
                            ]
                        },
                        {
                            "main_document": "99999999999",
                            "name": "Usuário 4",
                            "side": "Active",
                            "person_type": "Desconhecido",
                            "documents": [
                                {
                                    "document": "99999999999",
                                    "document_type": "cnpj"
                                }
                            ],
                            "lawyers": [
                                {
                                    "name": "Usuário 5",
                                    "documents": []
                                }
                            ]
                        },
                        {
                            "name": "Usuário 4",
                            "side": "Active",
                            "person_type": "Desconhecido",
                            "documents": [],
                            "lawyers": [
                                {
                                    "name": "Usuário 5",
                                    "documents": []
                                }
                            ]
                        },
                        {
                            "name": "Usuário 2",
                            "side": "Passive",
                            "person_type": "Desconhecido",
                            "documents": [],
                            "lawyers": [
                                {
                                    "name": "Usuário 3",
                                    "documents": []
                                }
                            ]
                        },
                        {
                            "name": "Usuário 5",
                            "side": "Active",
                            "person_type": "Advogado",
                            "documents": []
                        },
                        {
                            "name": "Usuário 3",
                            "side": "Passive",
                            "person_type": "Advogado",
                            "documents": []
                        }
                    ],
                    "steps": [
                        {
                            "lawsuit_cnj": "9999999-99.9999.9.99.9999",
                            "lawsuit_instance": 1,
                            "step_date": "2019-07-16T00:00:00.000Z",
                            "private": false,
                            "tags": {
                                "crawl_id": "36fc0ffd-98fa-4990-bd6f-6a82e5565119"
                            },
                            "step_id": "56174b2e",
                            "content": "Início da Execução Juntado\n0003695-16.2019.8.26.0189 - Cumprimento de sentença",
                            "steps_count": 32,
                            "created_at": "2025-07-09T13:48:33.114Z",
                            "updated_at": "2025-08-11T18:57:39.041Z"
                        },
                        {
                            "lawsuit_cnj": "9999999-99.9999.9.99.9999",
                            "lawsuit_instance": 1,
                            "step_date": "2019-06-06T00:00:00.000Z",
                            "private": false,
                            "tags": {
                                "crawl_id": "36fc0ffd-98fa-4990-bd6f-6a82e5565119"
                            },
                            "step_id": "939794b9",
                            "content": "Arquivado Definitivamente",
                            "created_at": "2025-07-09T13:48:33.114Z",
                            "updated_at": "2025-08-11T18:57:39.041Z"
                        },
                        {
                            "lawsuit_cnj": "9999999-99.9999.9.99.9999",
                            "lawsuit_instance": 1,
                            "step_date": "2019-06-06T00:00:00.000Z",
                            "private": false,
                            "tags": {
                                "crawl_id": "36fc0ffd-98fa-4990-bd6f-6a82e5565119"
                            },
                            "step_id": "423978eb",
                            "content": "Trânsito em Julgado às partes\nCertidão de trânsito em julgado e remessa ao arquivo geral",
                            "created_at": "2025-07-09T13:48:33.114Z",
                            "updated_at": "2025-08-11T18:57:39.041Z"
                        }
                    ],
                    "attachments": [
                        {
                            "attachment_id": "60153051-1-1",
                            "attachment_date": "2019-02-15T16:00:41.000Z",
                            "attachment_name": "Petição (Outras)",
                            "extension": "pdf",
                            "status": "done",
                            "tags": {
                                "crawl_id": "424cd251-3d1f-407e-9d17-cb61219545aa"
                            },
                            "user_data": null
                        },
                        {
                            "attachment_id": "60153057-5-1",
                            "attachment_date": "2019-02-15T16:00:42.000Z",
                            "attachment_name": "Instrumento de Procuração",
                            "extension": "pdf",
                            "status": "done",
                            "tags": {
                                "crawl_id": "424cd251-3d1f-407e-9d17-cb61219545aa"
                            },
                            "user_data": null
                        },
                        {
                            "attachment_id": "60153061-6-1",
                            "attachment_date": "2019-02-15T16:00:43.000Z",
                            "attachment_name": "Guia",
                            "extension": "pdf",
                            "status": "done",
                            "tags": {
                                "crawl_id": "424cd251-3d1f-407e-9d17-cb61219545aa"
                            },
                            "user_data": null
                        },
                        {
                            "attachment_id": "60153064-7-1",
                            "attachment_date": "2019-02-15T16:00:44.000Z",
                            "attachment_name": "Guia",
                            "extension": "pdf",
                            "status": "done",
                            "tags": {
                                "crawl_id": "424cd251-3d1f-407e-9d17-cb61219545aa"
                            },
                            "user_data": null
                        }
                    ],
                    "related_lawsuits": [],
                    "crawler": {
                        "source_name": "JSaj - TJ - SP - Lawsuit - Auth - 1 instance",
                        "crawl_id": "a9b6820a-6c84-4db5-b4f4-2f1909aa3805",
                        "weight": 10,
                        "updated_at": "2025-08-13T18:43:47.770Z"
                    },
                    "metadata": {},
                    "county": "VARA JUIZADO ESP. CIVEL CRIM. DE FERNANDOPOLIS",
                    "amount": 5798,
                    "state": "SP",
                    "city": "FERNANDOPOLIS",
                    "justice_description": "JUSTIÇA ESTADUAL",
                    "last_step": {
                        "lawsuit_cnj": "9999999-99.9999.9.99.9999",
                        "lawsuit_instance": 1,
                        "step_date": "2019-07-16T00:00:00.000Z",
                        "private": false,
                        "tags": {
                            "crawl_id": "a9b6820a-6c84-4db5-b4f4-2f1909aa3805"
                        },
                        "step_id": "56174b2e",
                        "content": "Início da Execução Juntado\n0003695-16.2019.8.26.0189 - Cumprimento de sentença",
                        "steps_count": 32
                    },
                    "phase": "Execução ou cumprimento",
                    "status": "Ativo",
                    "name": "Usuário 4 X Usuário 2",
                    "created_at": "2025-08-13T18:43:51.016Z",
                    "updated_at": "2025-08-13T18:43:51.016Z",
                    "free_justice": false
                },
                "user_id": "7f8065a3-4891-428d-9456-dedfc12ff850",
                "created_at": "2025-08-13T18:40:54.982Z",
                "request_created_at": "2025-08-13T18:40:54.037Z",
                "tags": {
                    "debug": true,
                    "dashboard_id": null,
                    "cached_response": false,
                    "cached": false
                }
            }
        ]
    }

{
        "request_status": "completed",
        "page": 1,
        "page_count": 1,
        "all_pages_count": 1,
        "all_count": 1,
        "page_data": [
            {
                "request_id": "03abbf28-822e-45a0-a22c-098fbe157aa4",
                "response_id": "061c60b2-7fa9-4d20-87bb-1bedd31d5572",
                "origin": "api",
                "origin_id": "03abbf28-822e-45a0-a22c-098fbe157aa4",
                "response_type": "lawsuit",
                "response_data": {
                    "code": "9999999-99.9999.9.99.9999",
                    "justice": "8",
                    "tribunal": "26",
                    "instance": 1,
                    "distribution_date": "2019-02-15T16:00:00.000Z",
                    "judge": "Usuário teste",
                    "tribunal_acronym": "TJSP",
                    "secrecy_level": 0,
                    "tags": {
                        "crawl_id": "a9b6820a-6c84-4db5-b4f4-2f1909aa3805",
                        "dictionary_updated_at": "2025-08-13T18:43:48.143Z"
                    },
                    "subjects": [
                        {
                            "code": "",
                            "name": "PAGAMENTO"
                        }
                    ],
                    "classifications": [
                        {
                            "code": "7",
                            "name": "PROCEDIMENTO COMUM CÍVEL"
                        }
                    ],
                    "courts": [
                        {
                            "name": "1ª Vara Cível"
                        }
                    ],
                    "parties": [
                        {
                            "main_document": "99999999999",
                            "name": "Usuário 2",
                            "side": "Passive",
                            "person_type": "Desconhecido",
                            "documents": [
                                {
                                    "document": "99999999999",
                                    "document_type": "cpf"
                                }
                            ],
                            "lawyers": [
                                {
                                    "name": "Usuário 3",
                                    "documents": []
                                }
                            ]
                        },
                        {
                            "main_document": "99999999999",
                            "name": "Usuário 4",
                            "side": "Active",
                            "person_type": "Desconhecido",
                            "documents": [
                                {
                                    "document": "99999999999",
                                    "document_type": "cnpj"
                                }
                            ],
                            "lawyers": [
                                {
                                    "name": "Usuário 5",
                                    "documents": []
                                }
                            ]
                        },
                        {
                            "name": "Usuário 4",
                            "side": "Active",
                            "person_type": "Desconhecido",
                            "documents": [],
                            "lawyers": [
                                {
                                    "name": "Usuário 5",
                                    "documents": []
                                }
                            ]
                        },
                        {
                            "name": "Usuário 2",
                            "side": "Passive",
                            "person_type": "Desconhecido",
                            "documents": [],
                            "lawyers": [
                                {
                                    "name": "Usuário 3",
                                    "documents": []
                                }
                            ]
                        },
                        {
                            "name": "Usuário 5",
                            "side": "Active",
                            "person_type": "Advogado",
                            "documents": []
                        },
                        {
                            "name": "Usuário 3",
                            "side": "Passive",
                            "person_type": "Advogado",
                            "documents": []
                        }
                    ],
                    "steps": [
                        {
                            "lawsuit_cnj": "9999999-99.9999.9.99.9999",
                            "lawsuit_instance": 1,
                            "step_date": "2019-07-16T00:00:00.000Z",
                            "private": false,
                            "tags": {
                                "crawl_id": "36fc0ffd-98fa-4990-bd6f-6a82e5565119"
                            },
                            "step_id": "56174b2e",
                            "content": "Início da Execução Juntado\n0003695-16.2019.8.26.0189 - Cumprimento de sentença",
                            "steps_count": 32,
                            "created_at": "2025-07-09T13:48:33.114Z",
                            "updated_at": "2025-08-11T18:57:39.041Z"
                        },
                        {
                            "lawsuit_cnj": "9999999-99.9999.9.99.9999",
                            "lawsuit_instance": 1,
                            "step_date": "2019-06-06T00:00:00.000Z",
                            "private": false,
                            "tags": {
                                "crawl_id": "36fc0ffd-98fa-4990-bd6f-6a82e5565119"
                            },
                            "step_id": "939794b9",
                            "content": "Arquivado Definitivamente",
                            "created_at": "2025-07-09T13:48:33.114Z",
                            "updated_at": "2025-08-11T18:57:39.041Z"
                        },
                        {
                            "lawsuit_cnj": "9999999-99.9999.9.99.9999",
                            "lawsuit_instance": 1,
                            "step_date": "2019-06-06T00:00:00.000Z",
                            "private": false,
                            "tags": {
                                "crawl_id": "36fc0ffd-98fa-4990-bd6f-6a82e5565119"
                            },
                            "step_id": "423978eb",
                            "content": "Trânsito em Julgado às partes\nCertidão de trânsito em julgado e remessa ao arquivo geral",
                            "created_at": "2025-07-09T13:48:33.114Z",
                            "updated_at": "2025-08-11T18:57:39.041Z"
                        }
                    ],
                    "attachments": [
                        {
                            "attachment_id": "60153051-1-1",
                            "attachment_date": "2019-02-15T16:00:41.000Z",
                            "attachment_name": "Petição (Outras)",
                            "extension": "pdf",
                            "status": "pending",
                            "tags": {
                                "crawl_id": "424cd251-3d1f-407e-9d17-cb61219545aa"
                            },
                            "user_data": null
                        },
                        {
                            "attachment_id": "60153057-5-1",
                            "attachment_date": "2019-02-15T16:00:42.000Z",
                            "attachment_name": "Instrumento de Procuração",
                            "extension": "pdf",
                            "status": "pending",
                            "tags": {
                                "crawl_id": "424cd251-3d1f-407e-9d17-cb61219545aa"
                            },
                            "user_data": null
                        },
                        {
                            "attachment_id": "60153061-6-1",
                            "attachment_date": "2019-02-15T16:00:43.000Z",
                            "attachment_name": "Guia",
                            "extension": "pdf",
                            "status": "pending",
                            "tags": {
                                "crawl_id": "424cd251-3d1f-407e-9d17-cb61219545aa"
                            },
                            "user_data": null
                        },
                        {
                            "attachment_id": "60153064-7-1",
                            "attachment_date": "2019-02-15T16:00:44.000Z",
                            "attachment_name": "Guia",
                            "extension": "pdf",
                            "status": "pending",
                            "tags": {
                                "crawl_id": "424cd251-3d1f-407e-9d17-cb61219545aa"
                            },
                            "user_data": null
                        }
                    ],
                    "related_lawsuits": [],
                    "crawler": {
                        "source_name": "JSaj - TJ - SP - Lawsuit - Auth - 1 instance",
                        "crawl_id": "a9b6820a-6c84-4db5-b4f4-2f1909aa3805",
                        "weight": 10,
                        "updated_at": "2025-08-13T18:43:47.770Z"
                    },
                    "metadata": {},
                    "county": "VARA JUIZADO ESP. CIVEL CRIM. DE FERNANDOPOLIS",
                    "amount": 5798,
                    "state": "SP",
                    "city": "FERNANDOPOLIS",
                    "justice_description": "JUSTIÇA ESTADUAL",
                    "last_step": {
                        "lawsuit_cnj": "9999999-99.9999.9.99.9999",
                        "lawsuit_instance": 1,
                        "step_date": "2019-07-16T00:00:00.000Z",
                        "private": false,
                        "tags": {
                            "crawl_id": "a9b6820a-6c84-4db5-b4f4-2f1909aa3805"
                        },
                        "step_id": "56174b2e",
                        "content": "Início da Execução Juntado\n0003695-16.2019.8.26.0189 - Cumprimento de sentença",
                        "steps_count": 32
                    },
                    "phase": "Execução ou cumprimento",
                    "status": "Ativo",
                    "name": "Usuário 4 X Usuário 2",
                    "created_at": "2025-08-13T18:43:51.016Z",
                    "updated_at": "2025-08-13T18:43:51.016Z",
                    "free_justice": false
                },
                "user_id": "7f8065a3-4891-428d-9456-dedfc12ff850",
                "created_at": "2025-08-13T18:40:54.982Z",
                "request_created_at": "2025-08-13T18:40:54.037Z",
                "tags": {
                    "debug": true,
                    "dashboard_id": null,
                    "cached_response": false,
                    "cached": false
                }
            }
        ]
    },
    {
            "request_id": "3c6614e3-25f1-4df4-9675-694c3ea01499",
            "response_id": "2dc884c1-e57b-47be-ba6c-568b3f066799",
            "origin": "api",
            "origin_id": "3c6614e3-25f1-4df4-9675-694c3ea014d9",
            "response_type": "summary",
            "response_data": {
                "data": [
                    "## Resumo\n\nO processo de número <strong className=\"text-primary\">0000000-00.0000.0.00.0000</strong> trata-se de uma disputa judicial envolvendo direitos autorais, 
                    onde o requerente, Usuário 1, alega ter seus direitos violados pelo requerido, Usuário 2. A distribuição do processo ocorreu no dia 7 de agosto de 2015 e, após trâmites 
                    legais e recursos, o processo foi arquivado definitivamente em 22 de novembro de 2024. Durante todo esse tempo, houve várias movimentações, incluindo cumprimento e execução 
                    de sentença.\n\n## Partes\n\n<ul>\n  <li>\n    <p>\n      <strong className=\"text-foreground text-base leading-5 font-semibold\">Usuário 1</strong>\n      
                    <span className=\"text-muted-foreground text-sm\">CPF: 000.000.000-00</span>\n      <br />\n      <p className=\"text-foreground/70 text-md font-normal\">\n        Requerente 
                    da ação, buscando a proteção de seus direitos autorais que alega terem sido violados.\n      </p>\n      <br className=\"last-of-type:hidden\"/>\n    </p>\n  </li>\n  <li>\n    
                    <p>\n      <strong className=\"text-foreground text-base leading-5 font-semibold\">Usuário 2</strong>\n      <span className=\"text-muted-foreground text-sm\">
                    CNPJ: 00.000.000/0000-00</span>\n      <br />\n      <p className=\"text-foreground/70 text-md font-normal\">\n        Requerido na ação, acusado de violar direitos autorais do 
                    requerente.\n      </p>\n      <br className=\"last-of-type:hidden\"/>\n    </p>\n  </li>\n</ul>\n\n## Classe\n\n<ul>\n  <li>\n    <p>\n      <strong className=\"text-foreground 
                    text-base leading-5 font-semibold\">Procedimento Comum Cível</strong>\n      <br />\n      <p className=\"text-foreground/70 text-md font-normal\">\n        É uma classe 
                    processual genérica para ações que vão a julgamento com base no direito civil, não enquadrando-se em procedimentos especiais.\n      </p>\n    </p>\n  </li>\n</ul>\n\n## 
                    Assuntos\n\n<ul>\n  <li>\n    <p>\n      <strong className=\"text-foreground text-base leading-5 font-semibold\">Direito Autoral</strong>\n      <br />\n      
                    <p className=\"text-foreground/70 text-md font-normal\">\n        O assunto do processo envolve disputas relacionadas à proteção da exclusividade de uso, gozo e disposição de uma 
                    obra intelectual criada.\n      </p>\n      <br />\n    </p>\n  </li>\n</ul>\n\n## Movimentações\n\nEm termos gerais, o processo foi marcado por uma longa tramitação. Inicialmente, 
                    o <span className=\"font-bold\">requerente</span> Usuário 1 buscou judicialmente a defesa de seus direitos autorais, alegando violações por parte do <span className=\"font-bold\">requerido</span>, 
                    Usuário 2. Durante o caso, houve apelação (tentativa de modificar uma decisão desfavorável) pelo requerente, além de embargos de declaração (pedidos de esclarecimento sobre a decisão), ambos não 
                    acolhidos, mantendo-se inalterada a decisão contestada. Em <span className=\"text-primary\">23 de julho de 2023</span>, houve o recebimento dos autos do Tribunal de Justiça com trânsito 
                    em julgado (quando não há mais possibilidade de recurso) da decisão que negou provimento ao recurso do requerente. Seguiu-se a execução da sentença, na qual se busca o cumprimento do 
                    que foi determinado pela Justiça, e finalmente, o <span className=\"text-primary\">processo foi arquivado definitivamente em 22 de novembro de 2024</span>, sinalizando a conclusão do litígio."
                ],
                "origin_id": "0f5baa30-f681-47cd-a381-01d489f4d079",
                "origin": "response"
            },
            "user_id": "7f8065a3-4891-9999-9456-dedfc12ff899",
            "created_at": "2026-03-18T17:18:18.156Z",
            "request_created_at": "2026-03-18T17:16:15.810Z"
        }

What you receive back

The return is paginated and contains the Lawsuit Object inside the page_data array. If you requested Judit AI (use_judit_ia: true), the judit_ia object brings a human-readable summary of the lawsuit + structured listing of parties, classes, subjects and movements.

Field	Type	Description
`request_status`	string	Final request status (`completed`, `created`, `processing`).
`page` / `page_count` / `all_pages_count` / `all_count`	number	Pagination.
`page_data`	array	List of responses — usually 1 per request.
`page_data[].response_type`	string	`lawsuit`, `lawsuits`, `application_error`, etc.
`page_data[].response_data`	object	Main content — follows the Lawsuit Schema.
`page_data[].cached_response`	boolean	`true` if it came from datalake; `false` if it came fresh from court.

How attachments work (`attachments`)

This is the part of the lawsuit query that raises the most questions, so it is worth understanding the mechanism before requesting the capture.

The `attachments` array always comes in the response

Every lawsuit query returns the attachments array inside the Lawsuit Object — whether or not you sent with_attachments. Each item in the array is an object representing one attachment that exists in the lawsuit today, with its identifier, name, date and extension. In other words: the array is the reference of every attachment in the lawsuit, not the list of files Judit has already downloaded. Seeing an attachment listed there does not mean the file was captured.

What matters is each attachment’s `status`

Inside each object in the array there is a status property. It — and only it — tells you whether that specific file has been captured and is available for download:

`status`	What it means
`pending`	The attachment exists in the lawsuit, but the file has not been captured by Judit yet. It cannot be downloaded.
`done`	The file has been captured and is stored in Judit’s buckets, ready for download.

"attachments": [
    {
        "attachment_id": "60153051-1-1",
        "attachment_name": "Petição (Outras)",
        "extension": "pdf",
        "status": "done"
    },
    {
        "attachment_id": "60153057-5-1",
        "attachment_name": "Instrumento de Procuração",
        "extension": "pdf",
        "status": "pending"
    }
]

In the example above, the first attachment can already be downloaded; the second cannot.

Query without attachment capture

When the request is made without with_attachments (or with with_attachments: false), the attachments array still comes back listing every attachment in the lawsuit — but all of them with status: "pending". You see what exists in the lawsuit, and no file is downloaded. This is useful to size up the lawsuit before requesting the capture: you can count how many attachments exist and work out how many requests will be needed.

Query with attachment capture and the 1,000 limit

When you send with_attachments: true, Judit captures up to 1,000 attachments per request. In the response, those up to 1,000 attachments move from pending to done. The rest stay pending. If the lawsuit has more than 1,000 attachments, you must repeat the lawsuit query for the same CNJ, again with with_attachments: true. With each new request, the next batch of up to 1,000 attachments moves from pending to done. Here is how it looks for a lawsuit with 2,500 attachments:

Request	Attachments captured in it	Total marked `done`	Still `pending`
1st query with `with_attachments: true`	1,000	1,000	1,500
2nd query with `with_attachments: true`	1,000	2,000	500
3rd query with `with_attachments: true`	500	2,500	0

The capture is finished when no attachment in the array has status: "pending". There is no field such as “X attachments remaining”: the correct way to know you are done is to iterate over the attachments array and check each object’s status.

Recommended flow

Run the query requesting attachments

Send the request for the desired CNJ with "with_attachments": true.

Iterate over the attachments array in the result

In Step 3, when capturing the result, iterate over attachments and count how many objects have status: "pending".

Repeat while there are pending ones

If there are still attachments in pending, send a new lawsuit query for the same CNJ, also with "with_attachments": true. Each repetition captures the next batch of up to 1,000.

Stop when there are no pending ones left

When every object in the array has status: "done", all of the lawsuit’s attachments have been captured.

Billing for the repetitions

Every request is billed as a lawsuit query + attachment capture. This applies to all calls, including the repetitions made only to capture the following batches of 1,000 attachments. A lawsuit with 2,500 attachments therefore costs 3 lawsuit queries with attachment capture — not one.

If the attachment volume is a cost concern, first run a query without with_attachments to find out how many attachments the lawsuit has and estimate the number of repetitions. That initial query is billed as a lawsuit query, without the attachment capture cost.

Next steps

👉 Webhook & Callbacks — receive automatic notifications when the search ends.
👉 Hot Storage (sync) — for an immediate response (cached).
👉 Has Lawsuits? (true/false) — lightweight boolean gate.
👉 Lawsuits Count — only the total.
👉 Error Codes — troubleshooting.

Getting Started

Core Concepts

Data Models (Schemas)

Asynchronous Requests

Synchronous Requests

Tracking

Registration Data

Criminal Records

File Transfer

Credentials Vault

Webhook

Resources

When to use

Forced refresh

Full cover + steps

AI summary

Lawsuits under secrecy

Asynchronous on-demand flow (overview)

Understanding the Asynchronous Flow

Step 1: Creating the Search Request

Payload Parameters (Body)

Searching Superior Instances

When to enable it

Request cost

Request Example (POST)

Step 2: Check the Request Status

Step 3: Capture the Result (The Lawsuit)

Request example (GET)

Response examples

What you receive back

How attachments work (`attachments`)

The `attachments` array always comes in the response

What matters is each attachment’s `status`

Query without attachment capture

Query with attachment capture and the 1,000 limit

Recommended flow

Billing for the repetitions

Next steps

​When to use

Forced refresh

Full cover + steps

AI summary

Lawsuits under secrecy

​Asynchronous on-demand flow (overview)

​Understanding the Asynchronous Flow

​Step 1: Creating the Search Request

​Payload Parameters (Body)

​Searching Superior Instances

​When to enable it

​Request cost

​Related lawsuits in other instances

​Request Example (POST)

​Step 2: Check the Request Status

​Step 3: Capture the Result (The Lawsuit)

​Request example (GET)

​Response examples

​What you receive back

​How attachments work (attachments)

​The attachments array always comes in the response

​What matters is each attachment’s status

​Query without attachment capture

​Query with attachment capture and the 1,000 limit

​Recommended flow

​Billing for the repetitions

​Next steps

When to use

Asynchronous on-demand flow (overview)

Understanding the Asynchronous Flow

Step 1: Creating the Search Request

Payload Parameters (Body)

Searching Superior Instances

When to enable it

Request cost

Related lawsuits in other instances

Request Example (POST)

Step 2: Check the Request Status

Step 3: Capture the Result (The Lawsuit)

Request example (GET)

Response examples

What you receive back

How attachments work (`attachments`)

The `attachments` array always comes in the response

What matters is each attachment’s `status`

Query without attachment capture

Query with attachment capture and the 1,000 limit

Recommended flow

Billing for the repetitions

Next steps