CUSTOS API – Federal government costs

About

The CUSTOS API (https://apidatalake.tesouro.gov.br/docs/custos/) provides cost data from the Federal Government Cost Portal (Portal de Custos do Governo Federal). It breaks down costs into six categories: active staff, retired staff, pensioners, depreciation, transfers, and other costs.

All parameters in this API are optional — you can call any function without arguments to retrieve the full dataset.

Performance warning

The CUSTOS API is slow. Its server default is only 250 rows per page; the package raises this to 500 by default (lowered from 1000 in 0.2.1 after the upstream load balancer started cutting broader queries). Even with 500-row pages, unfiltered queries routinely hit HTTP 504 timeouts. Always filter your queries by at least:

• year and month — year-only queries are the single most common cause of 504s; always pin a single month for production work
• org_level1 + org_level2 (reduce to a specific organization)
• legal_nature (reduce to a legal nature category)
• max_rows (set a hard cap for testing)

The package retries automatically on 504s (up to 5 attempts with progressive backoff). When pagination fails after the first page, the rows already fetched are not discarded — you receive a partial tibble with attr(result, "partial") = TRUE and attr(result, "last_page_error") describing the failure. Always check these attributes when working with broad queries.

Available functions

Parameter mapping

All six functions share the same optional filters:

SIORG codes are automatically zero-padded: you can pass 244, "244", or "000244" — all produce the same query.

Examples

library(tesouror)
library(dplyr)

# Step 1: Look up SIORG codes for the organization you want
orgaos <- get_siorg_organizations(power_code = 1, sphere_code = 1)
mec <- orgaos |> filter(sigla == "MEC")          # code 244
inep <- orgaos |> filter(sigla == "INEP")         # code 249

# Step 2: Query CUSTOS with org AND month filters (year-only is unsafe!)
# Active staff costs for INEP, June 2023
ativos_inep <- get_costs_active_staff(
  year = 2023, month = 6,
  org_level1 = 244,     # MEC — auto-padded to "000244"
  org_level2 = 249      # INEP — auto-padded to "000249"
)

# Always check whether pagination completed; on 504 mid-stream the
# package returns a partial tibble rather than dropping the data.
if (isTRUE(attr(ativos_inep, "partial"))) {
  message("Partial result — last page failed: ",
          attr(ativos_inep, "last_page_error"))
}

# Pensioner costs for INEP, June 2023 only
pensionistas_inep <- get_costs_pensioners(
  year = 2023, month = 6,
  org_level1 = 244,
  org_level2 = 249
)

# Quick test: just grab the first 100 rows
sample <- get_costs_active_staff(
  year = 2023, month = 6,
  legal_nature = 3,
  max_rows = 100
)