Skip to main content
POST
Execute a dataset query

Authorizations

Authorization
string
header
required

OAuth2 Authorization Code flow

Query Parameters

expand
string

Comma-separated fields to expand (e.g., "dataset")

fields
string

Comma-separated optional response fields. Supports "summary.short", "summary.long", and "summary.mdx".

Body

application/json
dataset
string
required

Dataset slug to query

Example:

"empresas"

params
object
required

Query parameters. Varies by dataset.

asOfDate
string

Logical reference date for the query (YYYY-MM-DD)

Example:

"2024-01-31"

mock

Enable mock mode. Use true/"default" for default example, or specify example key (e.g., "outro_exemplo")

Example:

true

requestId
string

Request ID

Example:

"req_123"

targetDocument
string

Target document (CNPJ/CPF) for property mapping. Used when the query result does not contain the document identifier.

Example:

"57778216000108"

cache
boolean
default:true

Enable caching. Set to false to bypass cache and force fresh data.

Example:

false

parent
object

Parent dataset query reference. Child queries persist zero cost.

export
enum<string> | null

Export task dataset summary PDF. "background" starts async export; "wait" returns the download URL.

Available options:
background,
wait,
null

Response

Query results

object
enum<string>
required

Object type identifier

Available options:
query
Example:

"query"

status
enum<string>
required

Query execution status

Available options:
success,
partial_success,
error,
pending
dataset
object
required

Dataset being queried (minimal reference)

asOfDate
string
required

Date for which data is queried

Example:

"2025-11-21"

createdAt
string<date-time>
required

Query creation timestamp

Example:

"2025-11-21T19:00:00.000Z"

isMock
boolean
required

Whether this is a mock query (testing mode)

Example:

false

cacheStatus
enum<string>
required
Available options:
hit,
miss
results
object[]
required

Query results. Each item follows the schema defined by the dataset being queried.

rawParams
object
required

Raw query parameters used for this query

id
string

Query execution ID

Example:

"qry_abc123"

provider
object

Provider used for the query

createdBy
object

Principal who created this query

requestId
string
summary

Rendered query summary markdown or MDX when requested via ?fields=summary.short, summary.long, summary.mdx, and/or summary.mdx-list. Single format → string. Multiple formats → object { short, long, mdx, "mdx-list" }.

attempts
number
duration
number

Query duration in milliseconds

errorMessage
string
cost
number

Query cost in cents (0 for cached queries)

affectedCanonicalTargets
object[]

Canonical entity query targets impacted by this dataset execution.

rawResponseProvider
object[] | null

Raw provider response captured during query execution.

parent
object

Parent dataset query reference

export
object

PDF export generated for this query