Falcao — National Labor-Justice Jurisprudence (CSJT)

FalcaoScraper queries the Jurisprudencia Nacional system of the Brazilian Labor Justice (Justica do Trabalho), hosted by the CSJT at https://jurisprudencia.jt.jus.br. A single search endpoint spans the TST and all 24 TRTs across five document collections.

Method	Description
listar_decisoes	Jurisprudence search — returns a DataFrame
listar_decisoes_download	Downloads the raw JSON pages to disk
listar_decisoes_parse	Parses a folder produced by listar_decisoes_download

Collections (colecao argument): acordaos (default), sentencas, decisoesmonocraticas, precedentes, recursorevista.

Notes: the public (unauthenticated) endpoint only allows page sizes of 5 or 10 (tamanho_pagina) and caps results at 10,000 per query.

Basic search

This example requests two pages. Always select a bounded number of pages for exploratory queries. The backend can respond with HTTP 429 and a long wait. Increasing sleep_time does not cancel an active block.

On 2026-10-03, five successful probes, including three consecutive calls in one session, each reported x-rate-limit-remaining: 49. Later that day, HTTP 429 reported a wait of 27,720 seconds at 19:17:44 UTC, pointing to release at 23:59:44 in Brasilia. This is consistent with the earlier midnight-reset hypothesis, but the quota size and the meaning of the successful-response counter remain unverified. The client does not use that counter to reject larger searches in advance. See issue #350.

If listar_decisoes fails after receiving pages, it preserves their JSON files in their own folder under the system temporary directory; the scraper’s download_path is not used. The exception note gives the folder to pass to listar_decisoes_parse for a partial result. This does not resume the interrupted search. Successful calls remove their temporary files.

import juscraper as jus

falcao = jus.scraper("falcao")
df = falcao.listar_decisoes("dano moral", paginas=2, tamanho_pagina=10)
print(df.shape)
df.head(3)

(20, 21)

	siglaClasseProcesso	classeProcesso	relator	tribunal	idGabinete	gabinete	idTurma	turma	textoAcordao	ementa	...	idDocumentoAcordao	referenciaLegislativa	prioridades	score	processo	colecao	data_julgamento	data_juntada	classe	classe_sigla
0	ROT	Recurso Ordinário Trabalhista	MARCO ANTONIO PAULINELLI DE CARVALHO	TRT3	118.0	Gabinete de Desembargador n. 27	21	11ª Turma	<table width="100%" cellspacing="2" cellpaddin...	DANO MORAL COLETIVO. CARACTERIZAÇÃO. Comprovad...	...	52519235	[art_186_ccb, art_794_clt, trt3, eca, art_319_...	None	163.56393	0010742-41.2019.5.03.0089	acordaos	08/07/2020	09/07/2020	Recurso Ordinário Trabalhista	ROT
1	AP	Agravo de Petição	Manoel Barbosa da Silva	TRT3	60.0	Gabinete de Desembargador n. 23	17	05ª Turma	<table width="100%" cellspacing="2" cellpaddin...	None	...	54012484	[trt3, prgf_2_art_791_clt, art_477_clt, iv_prg...	None	161.79614	0010172-33.2020.5.03.0182	acordaos	04/08/2020	07/08/2020	Agravo de Petição	AP
2	CSJT-PCA	Procedimento de Controle Administrativo	FRANCISCO JOSE PINHEIRO CRUZ	CSJT	NaN	None	405	Conselho Superior da Justiça do Trabalho	<html>\n <head>\n <style>\n <!--\n ...	PROCEDIMENTO DE CONTROLE ADMINISTRATIVO. TRT d...	...	e70315f87fe4b814d1066dd2ae86b328	[art_24_resolucao_csjt_68_10, resolucao_cnj_83...	None	161.42017	0025151-21.2015.5.90.0000	acordaos	24/03/2017	30/03/2017	Procedimento de Controle Administrativo	CSJT-PCA

3 rows × 21 columns

Available columns

df.columns.tolist()

['siglaClasseProcesso',
 'classeProcesso',
 'relator',
 'tribunal',
 'idGabinete',
 'gabinete',
 'idTurma',
 'turma',
 'textoAcordao',
 'ementa',
 'possuiEmenta',
 'idDocumentoAcordao',
 'referenciaLegislativa',
 'prioridades',
 'score',
 'processo',
 'colecao',
 'data_julgamento',
 'data_juntada',
 'classe',
 'classe_sigla']

Preview an ementa

The acordaos collection ships the ementa, returned as plain text (HTML stripped).

print(df["ementa"].iloc[0][:300])

DANO MORAL COLETIVO. CARACTERIZAÇÃO. Comprovado o ato ilícito praticado pela reclamada, com violação ao ordenamento jurídico e sonegação de direito trabalhista assegurado aos empregados (descanso semanal remunerado), é inegável a ofensa aos direitos fundamentais dos trabalhadores, sobretudo a dignid

Using filters

Filters are validated by the InputListarDecisoesFalcao pydantic schema. Multi-value filters accept a string or a list of strings.

df_filtrado = falcao.listar_decisoes(
    "hora extra",
    paginas=1,
    tribunais=["TST", "TRT3"],       # court(s)
    ordenacao="mais_recente",         # mais_relevante | mais_recente | menos_recente
    data_juntada_inicio="2023-01-01",  # ISO or DD/MM/YYYY, filters dataJuntada
    data_juntada_fim="2023-12-31",
)
print(df_filtrado.shape)
df_filtrado[["processo", "tribunal", "data_juntada"]].head()
df_filtrado.head()

(10, 21)

	siglaClasseProcesso	classeProcesso	relator	tribunal	idGabinete	gabinete	idTurma	turma	textoAcordao	ementa	...	idDocumentoAcordao	referenciaLegislativa	prioridades	score	processo	colecao	data_julgamento	data_juntada	classe	classe_sigla
0	AIRR	Agravo de Instrumento em Recurso de Revista	SERGIO PINTO MARTINS	TST	None	None	22	8ª Turma	<!DOCTYPE html><html xmlns="http://www.w3.org/...	AGRAVO EM AGRAVO DE INSTRUMENTO EM RECURSO DE ...	...	fc34ba2ee76e19dd51779e85d17f274b	[art_389_cpc, art_896_clt, sumula_126_tst, art...	None	NaN	0000152-95.2014.5.02.0351	acordaos	13/12/2023	26/12/2023	Agravo de Instrumento em Recurso de Revista	AIRR
1	RR	Recurso de Revista	SERGIO PINTO MARTINS	TST	None	None	22	8ª Turma	<![CDATA[<p align="justify"><b>A C Ó R D Ã O</...	<p align="justify"><b>RECURSO DE REVISTA -REGÊ...	...	aa6472419237b828bfa9396814a1ecec	[art_896_clt, art_7_cf, i_prgf_1_art_896_clt, ...	None	NaN	0000472-53.2022.5.09.0325	acordaos	13/12/2023	26/12/2023	Recurso de Revista	RR
2	AIRR	Agravo de Instrumento em Recurso de Revista	SERGIO PINTO MARTINS	TST	None	None	22	8ª Turma	<!DOCTYPE html><html xmlns="http://www.w3.org/...	AGRAVO DE INSTRUMENTO EM RECURSO DE REVISTA DO...	...	1fac777f2b238bdaffdc786c5b4347dd	[v_sumula_331_tst, art_896_clt, i_prgf_1_art_8...	None	NaN	0000659-70.2020.5.06.0016	acordaos	13/12/2023	26/12/2023	Agravo de Instrumento em Recurso de Revista	AIRR
3	AIRR	Agravo de Instrumento em Recurso de Revista	SERGIO PINTO MARTINS	TST	None	None	22	8ª Turma	<!DOCTYPE html><html xmlns="http://www.w3.org/...	AGRAVO DE INSTRUMENTO EM RECURSO DE REVISTA IN...	...	66f00d3318ee717e73ad5619c740809e	[i_prgf_1_art_896_clt, iii_prgf_1_art_896_clt,...	None	NaN	0000820-38.2021.5.09.0121	acordaos	13/12/2023	26/12/2023	Agravo de Instrumento em Recurso de Revista	AIRR
4	AIRR	Agravo de Instrumento em Recurso de Revista	SERGIO PINTO MARTINS	TST	None	None	22	8ª Turma	<![CDATA[<p align="justify">A C Ó R D Ã O<br/>...	<p align="justify"><b>7ª Turma</b><br/></p><p ...	...	e12d133d21853f9d128db32b62049d89	[prgf_1_art_896_clt, sumula_126_tst, trt9, ii_...	None	NaN	0001084-91.2022.5.11.0015	acordaos	13/12/2023	26/12/2023	Agravo de Instrumento em Recurso de Revista	AIRR

5 rows × 21 columns

Querying different collections

The same search works across collections; each returns its own document shape, normalized to a common core (processo, colecao, tribunal, …).

Regional precedents can use idTema instead of id. Their processo key retains that identifier with a tribunal prefix; it is not a CNJ case number.

df_sent = falcao.listar_decisoes("acidente de trabalho", paginas=1, colecao="sentencas")
print("sentencas:", df_sent.shape)

df_sum = falcao.listar_decisoes("dano moral", paginas=1, colecao="precedentes")
print("precedentes:", df_sum.shape)
df_sum[["processo", "colecao", "tribunal"]].head()

sentencas: (10, 21)

precedentes: (10, 72)

	processo	colecao	tribunal
0	TST-SUM-392	precedentes	TST
1	TRT9-idTema43-IUJ_7_TRT9	precedentes	TRT9
2	TRT9-idTema88-IUJ_52_TRT9	precedentes	TRT9
3	TRT19-idIAC-4-13215-TRT19	precedentes	TRT19
4	TRT9-idTema64-IUJ_28_TRT9	precedentes	TRT9

Download and parse separately

Each listar_decisoes_download call creates its own subfolder and saves one raw JSON file per page (named {colecao}_{page}.json); listar_decisoes_parse reads a folder back into a DataFrame.

import tempfile, os, json

with tempfile.TemporaryDirectory() as tmp:
    pasta = falcao.listar_decisoes_download("dano moral", paginas=1, diretorio=tmp)
    arquivos = os.listdir(pasta)
    print("files:", arquivos)

    raw = json.load(open(os.path.join(pasta, arquivos[0])))
    print("quantidadeTotal:", raw["quantidadeTotal"])
    print("raw keys:", list(raw.keys()))

    df_parsed = falcao.listar_decisoes_parse(pasta)
    print("parsed:", df_parsed.shape)

files: ['acordaos_0001.json']
quantidadeTotal: 10000
raw keys: ['documentos', 'temasTopFive', 'quantidadeTotal']
parsed: (10, 21)