Pular para o conteúdo principal
POST
Pesquisa de ações
Escolha uma ação e seu período ou modo. Cada solicitação cria um Run; valores ausentes permanecem null. Índices financeiros usam frações e taxas macroeconômicas usam porcentagens. Leia result_status e charge_usd separadamente. Use action: screen com describe_filters: true para consultar os campos aceitos antes de filtrar. A saída nativa do Provider permanece no Run.

Cabeçalhos

idempotency-key
string
obrigatório

Gere um novo valor exclusivo (de preferência um UUID aleatório) para cada consulta independente, mesmo com os mesmos parâmetros no mesmo dia. Recupere a mesma execução com a chave e os parâmetros originais para obter o Run original sem outra cobrança. Alterar os parâmetros de execução com a mesma chave retorna 409; alterar task_id ou metadata não inicia um novo Run. As chaves opacas existentes continuam válidas para recuperação.

Minimum string length: 1

Corpo

application/json

Uma operação do FinancialDatasets por solicitação. Campos não utilizados são rejeitados antes da cobrança. Dados vazios ainda podem gerar cobrança. Não há conversão de moedas, estimativa de valores ausentes ou paginação automática.

action
enum<string>
obrigatório
Opções disponíveis:
company,
income,
balance_sheet,
cash_flow,
segments,
metrics,
earnings,
guidance,
prices,
news,
screen,
macro
provider
enum<string> | null

Padrão auto: seleciona o primeiro provedor de dados elegível na ordem de preferência da Glasser. Um provedor de dados nomeado precisa ser compatível com a solicitação e permitido pela sua Key; ele não usa fallback para outro provedor de dados. Os valores disponíveis estão listados abaixo.

Opções disponíveis:
auto,
financialdatasets
ticker
string | null
Minimum string length: 1
Pattern: ^[A-Za-z0-9.-]{1,12}$
cik
string | null
Minimum string length: 1
Pattern: ^\d{1,10}$
period
enum<string> | null
Opções disponíveis:
annual,
quarterly,
ttm
mode
enum<string> | null

Somente para metrics/prices/macro; o padrão é snapshot. history exige os parâmetros de período ou data da ação correspondente.

Opções disponíveis:
snapshot,
history
statement
enum<string> | null
Opções disponíveis:
all,
income,
balance_sheet,
cash_flow
macro
enum<string> | null
Opções disponíveis:
interest_rates,
inflation,
yield_curve,
banks,
inflation_series
bank
string | null
Required string length: 1 - 200
series
string | null
Required string length: 1 - 200
limit
integer | null
Intervalo obrigatório: 1 <= x <= 100
cursor
string | null
Required string length: 1 - 2000
interval
enum<string> | null
Opções disponíveis:
day,
week,
month,
year
start_date
string | null
Minimum string length: 1
Pattern: ^\d{4}-\d{2}-\d{2}$
end_date
string | null
Minimum string length: 1
Pattern: ^\d{4}-\d{2}-\d{2}$
metric_name
string | null
Required string length: 1 - 200
filters
object[] | null
Required array length: 1 - 20 elements
describe_filters
boolean | null

Somente para screen: true consulta gratuitamente os campos, aliases, operadores e categorias de empresas disponíveis; nesse modo, filters e limit são rejeitados.

report_period
string | null
Minimum string length: 1
Pattern: ^\d{4}-\d{2}-\d{2}$
report_period_gte
string | null
Minimum string length: 1
Pattern: ^\d{4}-\d{2}-\d{2}$
report_period_lte
string | null
Minimum string length: 1
Pattern: ^\d{4}-\d{2}-\d{2}$
report_period_gt
string | null
Minimum string length: 1
Pattern: ^\d{4}-\d{2}-\d{2}$
report_period_lt
string | null
Minimum string length: 1
Pattern: ^\d{4}-\d{2}-\d{2}$
filing_date
string | null
Minimum string length: 1
Pattern: ^\d{4}-\d{2}-\d{2}$
filing_date_gte
string | null
Minimum string length: 1
Pattern: ^\d{4}-\d{2}-\d{2}$
filing_date_lte
string | null
Minimum string length: 1
Pattern: ^\d{4}-\d{2}-\d{2}$
filing_date_gt
string | null
Minimum string length: 1
Pattern: ^\d{4}-\d{2}-\d{2}$
filing_date_lt
string | null
Minimum string length: 1
Pattern: ^\d{4}-\d{2}-\d{2}$
max_charge_usd
string | null

String decimal exata em USD (mínimo de 2, máximo de 6 casas decimais, uma única grafia canônica). Faça a soma com aritmética decimal ou multiplique por 10^6 — nunca use números de ponto flutuante.

Pattern: ^(0|[1-9]\d*)\.(\d{2}|\d{2}\d{0,3}[1-9])$
task_id
string | null

Agrupe Runs relacionados, incluindo o fallback automático, em uma única Task. Reutilize uma string estável e filtre a lista de Runs por task para recuperá-los.

metadata

Campos de rastreamento opcionais, retornados no Run e disponíveis como filtros. Eles nunca são enviados ao provedor de dados nem afetam o roteamento, o preço ou a idempotência.

  • Até 20 chaves: letras minúsculas, dígitos e sublinhados; comece com uma letra; no máximo 40 caracteres.
  • Valores: strings de 1–500 caracteres.
  • user_id: o ID opaco do seu usuário final, nunca o endereço de e-mail ou o nome dele.

Entradas inválidas são descartadas integralmente, não truncadas. A solicitação continua, e o Run retorna os campos que foram armazenados.

Resposta

Success

Os valores financeiros mantêm a moeda; índices e crescimento preservam as frações originais (0.3 significa 30%). As taxas macroeconômicas e day_change_percent são porcentagens. Campos ausentes são null. completed_at do Run é o horário da consulta, nunca um substituto para a data de observação.

id
string
obrigatório
run_url
string
obrigatório

Abra este Run no console. Requer associação ao Workspace.

provider
string
obrigatório
Pattern: ^[a-z0-9][a-z0-9-]*$
endpoint
string
obrigatório
Pattern: ^\/.+$
endpoint_version
integer
obrigatório
status
enum<string>
obrigatório

QUEUED ou RUNNING: ainda em andamento. COMPLETED: uma resposta do provedor de dados está disponível, incluindo respostas não 2xx. FAILED: consulte failure. STOPPED: interrompido antes do despacho. Leia charge_usd separadamente de status.

Opções disponíveis:
QUEUED,
RUNNING,
COMPLETED,
FAILED,
STOPPED
failure
object | null
obrigatório

Motivo da falha do Run. Não nulo somente quando status é FAILED.

input
object
obrigatório
output
object
obrigatório
provider_response
object | null
obrigatório

Não nulo somente quando status é COMPLETED.

  • Para respostas 2xx, output contém JSON nativo do provedor de dados (qualquer estrutura) ou nulo para um corpo vazio.
  • Para respostas não 2xx, error contém o corpo de erro do provedor de dados e output é nulo.

Os campos confidenciais são removidos de ambos os corpos.

charge_usd
string | null
obrigatório

Cobrança histórica total dos Runs listados, incluindo os reproduzidos ou lidos. É null até que todos sejam liquidados. Não é uma nova despesa da solicitação atual; request_charge a informa separadamente. Falhas também podem ser cobradas.

Pattern: ^(0|[1-9]\d*)\.(\d{2}|\d{2}\d{0,3}[1-9])$
charge_basis
object | null
obrigatório

Base de cobrança de um único Run ou nulo para um total de vários Runs. Leia runs[].charge_basis para cada cobrança.

stoppable
boolean
obrigatório

Indica se uma solicitação de interrupção pode ser aceita no momento. Isso não garante que o Run possa ser interrompido antes do despacho.

stop_requested_at
string<date-time> | null
obrigatório

Momento em que uma interrupção foi solicitada. O Run ainda pode continuar se o despacho já tiver começado.

created_at
string<date-time>
obrigatório

carimbo de data e hora UTC ISO-8601

started_at
string<date-time> | null
obrigatório

carimbo de data e hora UTC ISO-8601

completed_at
string<date-time> | null
obrigatório

carimbo de data e hora UTC ISO-8601

task_id
string | null
obrigatório
metadata
object
obrigatório

Seus campos de acompanhamento armazenados. Use-os para filtrar Runs. Eles nunca são enviados ao provedor de dados nem afetam o roteamento, o Price ou a idempotência.

  • Até 20 chaves: letras minúsculas, dígitos e sublinhados; comece com uma letra; no máximo 40 caracteres.
  • Valores: strings de 1–500 caracteres.
  • user_id: o ID opaco do seu usuário final, nunca o endereço de e-mail ou o nome dele.
action
enum<string>
obrigatório
Opções disponíveis:
company,
income,
balance_sheet,
cash_flow,
segments,
metrics,
earnings,
guidance,
prices,
news,
screen,
macro
result_status
enum<string>
obrigatório
Opções disponíveis:
success,
no_result,
error,
pending
error
object | null
obrigatório
runs
object[]
obrigatório
result_url
string
obrigatório

Caminho de URL autenticado e somente leitura para consultar este resultado normalizado e a cobrança total. Use com a origem da API. Não cria Runs nem retoma o fallback. GET /v1/runs/:id ainda retorna o Run nativo e individual.

response_file
object

Corpo completo e de grande tamanho do provedor de dados, entregue como arquivo JSON. O Glasser aplica um limite de recursos de 32 MiB ao corpo capturado e ao arquivo serializado. body_field identifica o campo substituído; output é null ou provider_response.error é omitido. Os links de download expiram em no máximo uma hora. Get Run com autenticação renova a URL enquanto o arquivo estiver disponível, por 7 dias. Leituras e downloads não executam nem cobram outro Run. Se state for link_pending, leia o mesmo Run para preparar o link sem outra execução ou cobrança. A URL concede acesso temporário de leitura: compartilhe-a apenas com os destinatários pretendidos.

review_invitation
object

Aparece no máximo uma vez por Run, na primeira entrega de alguns Runs concluídos. Depois de usar este resultado na tarefa, envie uma avaliação conforme indicado em instruction e continue. É opcional; nunca afeta o Run nem a cobrança.

request_charge
object

Evidência de admissão e cobrança da solicitação atual. Preserve created_run_ids durante o trabalho do usuário e conte cada Run liquidado uma única vez. Alterar task_id não transforma uma reprodução idempotente em um novo Run. A leitura de resultado tem cobrança zero e listas de admissão vazias.