Quickstart — Your first Miner query in 10 minutes - JUDIT

Public beta. Before starting, confirm with Judit’s commercial team that your API key has miner_enabled granted — without that flag, every call returns 403.

This is the minimum recipe to go from zero to your first batch of lawsuits. By the end you will have: counted how many lawsuits match your filters, spent credits on a real query, waited for processing, and paginated the results.

Prerequisites

Judit API key with miner_enabled: true (ask the commercial team).
Credit balance sufficient — check it on the dashboard.
An HTTP client (cURL, Postman or your language of choice).

Step 1: List available courts

Before filtering, you need the Miner-internal court IDs. They are not the acronyms: every court has its own numeric identifier in Miner.

curl --request GET \
  --url 'https://miner.production.judit.io/tribunals' \
  --header 'api-key: '"$JUDIT_API_KEY"

Snippet of the response:

[
  { "tribunal_id": 10,    "name": "TJSP" },
  { "tribunal_id": 18,    "name": "TJRJ" },
  { "tribunal_id": 1,     "name": "TRF3" },
  { "tribunal_id": 193,   "name": "TRF1" }
]

Note the IDs of the courts you want to cover. Full list at Supported courts.

Step 2: Count without spending credits (`/requests/count`)

The /requests/count route is free — use it to find out the volume before purchasing the query.

curl --request POST \
  --url 'https://miner.production.judit.io/requests/count' \
  --header 'api-key: '"$JUDIT_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "kind": "judgement-bond",
    "tribunals": [10, 18],
    "budget_years": [2024],
    "natures": ["common"]
  }'

Response:

{
  "request_id": 20,
  "filter": {
    "kind": "judgement-bond",
    "tribunals": [10, 18],
    "budget_years": [2024],
    "natures": ["common"]
  },
  "total_lawsuits": 7326,
  "status": "completed"
}

Field	Meaning
`total_lawsuits`	How many new lawsuits for your company match the filters (already excluding what you queried before).
`request_id`	ID of the count record — kept in history but not used downstream.
`status`	Always `completed` for count (it’s synchronous).

Step 3: Create the find (charges credits)

Once total_lawsuits makes sense for your case, trigger the real query with /requests/create. This is when credits are debited.

curl --request POST \
  --url 'https://miner.production.judit.io/requests/create' \
  --header 'api-key: '"$JUDIT_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "kind": "judgement-bond",
    "tribunals": [10, 18],
    "budget_years": [2024],
    "natures": ["common"],
    "responses_limit": 1000
  }'

💡 responses_limit is an optional cap on the number of materialized lawsuits in this query. If omitted, returns everything that matches. Use it to control cost when count returns a large volume.

Response (201 Created):

{
  "request_id": 47,
  "status": "pending",
  "cost": 12500
}

Field	Meaning
`request_id`	ID you’ll use in the next steps. Save it.
`status`	Always `pending` here.
`cost`	Total credits charged (sum of tier prices × counts). Detailed in Credits & billing.

If the response is 403 with code INSUFFICIENT_CREDITS or MISSING_CONFIGURATIONS, your account lacks balance or plan. See Common errors.

Step 4: Poll until done

Processing is async. Use GET /requests/{request_id} to track:

curl --request GET \
  --url 'https://miner.production.judit.io/requests/47' \
  --header 'api-key: '"$JUDIT_API_KEY"

Response while processing:

{
  "request_id": 47,
  "status": "pending",
  "type": "find",
  "total_lawsuits": 1000,
  "processed_lawsuits": 312,
  "filter": { "kind": "judgement-bond", "tribunals": [10, 18], "budget_years": [2024], "natures": ["common"] },
  "created_at": "2026-05-06T18:00:00.000Z",
  "updated_at": "2026-05-06T18:01:30.000Z"
}

Repeat every 30 s until status becomes completed. Typical time: 2–10 minutes for up to 1000 lawsuits.

Python (poll example)

import os, time, requests

API = "https://miner.production.judit.io"
HEADERS = {"api-key": os.environ["JUDIT_API_KEY"]}
REQ_ID = 47

while True:
    r = requests.get(f"{API}/requests/{REQ_ID}", headers=HEADERS, timeout=15)
    r.raise_for_status()
    data = r.json()
    print(f"{data['processed_lawsuits']}/{data['total_lawsuits']} — {data['status']}")
    if data["status"] in ("completed", "failed"):
        break
    time.sleep(30)

Step 5: Paginate the returned lawsuits

With status: completed, fetch the lawsuits via /responses:

curl --request GET \
  --url 'https://miner.production.judit.io/responses?request_id=47&page=1&page_size=50' \
  --header 'api-key: '"$JUDIT_API_KEY"

Response:

{
  "data": [
    {
      "lawsuit_id": 10293847,
      "tribunal_id": 10,
      "kind": "judgement-bond",
      "code": "9999999-99.9999.9.99.9999",
      "instance": 1,
      "name": "Plaintiff X Defendant",
      "amount": 152800.45,
      "is_enriched": true,
      "favorites": {},
      "created_at": "2026-05-06T18:05:21.000Z",
      "updated_at": "2026-05-06T18:05:21.000Z"
    }
  ],
  "page": 1,
  "page_size": 50,
  "total": 1000,
  "total_pages": 20
}

Iterate over page=2..20 until total_pages is exhausted. Each item follows LawsuitRepositoryOutput — lawsuit cover + parties, lawyers, steps and metadata.

Common errors

HTTP	Code	When	How to handle
`400`	(validation)	Invalid filter combination (e.g. `tags` with `kind: judgement-bond`).	Review rules in Concepts.
`403`	`MISSING_CREDITS`	Account has no credit balance.	Top up or contact commercial.
`403`	`MISSING_CONFIGURATIONS`	Plan has no Miner pricing tiers.	Request configuration.
`403`	`INSUFFICIENT_CREDITS`	Balance is below the computed `cost`.	Reduce `responses_limit` or top up.
`404`	`REQUEST_NOT_FOUND`	`request_id` does not exist for your company.	Check the ID; `request_id` is per-company, not global.
`422`	`REQUEST_NOT_COMPLETED`	Reading `/responses` while status is still `pending`.	Poll `/requests/{id}` until `completed`.
`422`	`INVALID_REQUEST_TYPE`	Reading `/responses` for a `count`-type request.	Use the `request_id` returned by `/requests/create`.

Next steps

Full concepts

All valid combinations of kind, natures, tags, amount_tier.

Credits & billing

How cost is computed and how to handle billing errors.

API Reference

Interactive spec with every endpoint and schema.

Court list

IDs and acronyms for the 60+ supported courts.

Getting Started

Concepts

API Reference · Miner

Quickstart — Your first Miner query in 10 minutes

Prerequisites

Step 1: List available courts

Step 2: Count without spending credits (`/requests/count`)

Step 3: Create the find (charges credits)

Step 4: Poll until done

Step 5: Paginate the returned lawsuits

Common errors

Next steps

Full concepts

Credits & billing

API Reference

Court list

​Prerequisites

​Step 1: List available courts

​Step 2: Count without spending credits (/requests/count)

​Step 3: Create the find (charges credits)

​Step 4: Poll until done

​Step 5: Paginate the returned lawsuits

​Common errors

​Next steps

Full concepts

Credits & billing

API Reference

Court list

Prerequisites

Step 1: List available courts

Step 2: Count without spending credits (`/requests/count`)

Step 3: Create the find (charges credits)

Step 4: Poll until done

Step 5: Paginate the returned lawsuits

Common errors

Next steps