Common Params

This page defines the shared query parameters used across endpoints: pagination, dates, filtering, sorting, and output format. It also highlights validation rules and common pitfalls.

Note: Fintatica uses page (zero-based) and page_size (not per_page).
If you’ve seen older examples using per_page, use page_size instead—this page is the source of truth.

Pagination

Param	Type	Default	Example
`page`	integer	`0`	`page=0`
`page_size`	integer	`100`	`page_size=250`

Usage

Termination rule: responses do not include paging metadata. Keep requesting page+1 until the number of items returned is less than your page_size (or zero).

Tips

Prefer incremental paging (e.g., 100–500) over huge pages—fewer retries and friendlier to rate limits.

Watch for off-by-one mistakes: the first page is page=0.

Dates & Ranges

Param	Type	Example	Semantics
`date`	string	`date=20250131`	Single day selection.
`from`	string	`from=20250101`	Start of range (inclusive).
`to`	string	`to=20250331`	End of range (inclusive).

Format: strictly YYYYMMDD.
Timezone: timestamps in responses are UTC unless the endpoint explicitly states Brazil Time; no global timezone override param.

Examples

Filtering

Filtering is endpoint-specific. If an endpoint supports filters, they’ll be documented on that page.

Equality filters: may be available on certain endpoints, documented where applicable.

Lists: use comma-separated values.

ids=ABCD11,XPTO3,IBOV

Ranges: when supported beyond from/to, endpoints define their own conventions.

URL encoding: If a value contains spaces or special characters, URL-encode it.

Sorting

Param	Values	Example	Notes
`sort_by`	field name	`sort_by=updated_at`	Field must be supported by the endpoint.
`sort_order`	`asc;desc`	`sort_order=desc`	If omitted, ordering is endpoint-specific and documented there.

Example

Output Format & Downloads

Default response format is JSON.

Param	Values (varies by endpoint)	Example	Effect
`format`	`json;csv;xml`	`format=csv`	Selects output format (if supported by that endpoint).
`download`	`1;true`	`format=csv&download=1`	Sets `Content-Disposition: attachment` to prompt a file download.

If an endpoint supports additional formats, it will say so on that endpoint’s page. If format is omitted, JSON is returned.

Booleans & Numbers

Booleans: accept true/false or 1/0. We recommend using true/false for clarity.

Integers/Floats: standard dot-decimal notation (e.g., 123, 45.67).

Validation & Unknown Params

Fintatica uses strict validation. Unknown or misspelled parameters result in 400 invalid_input with a structured payload. For input validation, error_data follows Zod’s flatten format.

Example: misspelled pageSize

{
  "success": false,
  "message": "Invalid input",
  "code": "invalid_input",
  "error_data": {
    "formErrors": ["Unrecognized key: \"pageSize\""],
    "fieldErrors": {
      "page_size": ["Expected integer between 1 and 1000"],
      "page": ["Expected integer 0 or greater"]
    }
  }
}

Gotchas people miss

Using YYYY-MM-DD → will fail; use YYYYMMDD.

Requesting page=-1 or page_size>1000 → will fail validation.

Mixing list delimiters (e.g., ids=a&ids=b) → not supported; use comma-separated (e.g., ids=a,b).

Assuming response includes total/next_page → it doesn’t; use the termination rule above.

Quick Reference

Pagination: page (0-based), page_size (1–1000; default 100)

Dates: date or from/to (inclusive), YYYYMMDD

Filters: endpoint-specific; lists are comma-separated

Sorting: sort_by, sort_order (asc/desc)

Format: format=json|csv|parquet (endpoint-specific), download=1 for attachment

Validation: strict; unknown params → 400 invalid_input (Zod flatten payload)

For rate limits, auth headers, and error semantics, see Authentication & Limits and Error Codes.

Pagination#

Usage#

Dates & Ranges#

Filtering#

Sorting#

Output Format & Downloads#

Booleans & Numbers#

Validation & Unknown Params#

Quick Reference#