Pular para o conteúdo principal
POST
Pesquisa de registros da SEC
Escolha uma das 11 ações: resolve, search, section, document, events, compensation, board, audit_fees, ipo, private_placements ou enforcement. Aplicam-se as regras normais de admissão, idempotência, Key Policy e cobrança do Run. Os dados nativos permanecem no Run. Alternativas de seção mantêm o mesmo número de acesso e Part/Item. source_run_id do índice verifica a origem. Anos de remuneração, datas de registro, aceitação e vigência são distintos. Não se inferem moedas ou dados ausentes; metas, valores vendidos, quantidades e receitas líquidas não são intercambiáveis. Ofertas exigem offering_type: form_d, form_c ou reg_a; Reg A admite all, 1-A, 1-K e 1-Z. Fiscalização exige record_type: actions, litigation, administrative ou aaer. Cada solicitação lê um Endpoint e uma página; totais ou cursores null não comprovam cobertura completa. Verifique result_status e cobranças separadamente. response_file entrega a saída normalizada grande completa. result_url reutiliza os dados sem nova execução ou Charge.

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
action
enum<string>
obrigatório
Opções disponíveis:
resolve,
search,
section,
document,
events,
compensation,
board,
audit_fees,
ipo,
private_placements,
enforcement
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,
secapi,
financialdatasets
ticker
string | null
Required string length: 1 - 12
cik
string | null
Minimum string length: 1
Pattern: ^\d{1,10}$
cusip
string | null
Minimum string length: 1
Pattern: ^[A-Za-z0-9]{6,9}$
name
string | null
Required string length: 1 - 100
query
string | null

Cláusula Lucene nativa do provedor. Filtros estruturados são combinados por AND; a sintaxe nativa não é corrigida. Uma consulta SEC API malformada pode retornar uma resposta vazia.

Required string length: 1 - 3500
form_types
string[] | null
Minimum array length: 1
Minimum string length: 1
accession_number
string | null
Minimum string length: 1
Pattern: ^\d{10}-\d{2}-\d{6}$
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}$
limit
integer | null
Intervalo obrigatório: 1 <= x <= 100
offset
integer | null
Intervalo obrigatório: 0 <= x <= 10000
cursor
string | null
Required string length: 1 - 2000
sort_order
enum<string> | null
Opções disponíveis:
asc,
desc
filing_url
string | null
Minimum string length: 1
url
string | null
Minimum string length: 1
form_type
enum<string> | null
Opções disponíveis:
10-K,
10-K/A,
10-Q,
10-Q/A,
8-K,
8-K/A
item
string | null

Identidade da seção: 10-K usa 1A ou 7; 10-Q usa part1item1 ou part2item1a; 8-K usa 4.01, 4.02 ou 5.02. Os códigos são verificados com o formulário e provedor solicitados.

Required string length: 1 - 30
source_run_id
string<uuid> | null
Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|[fF]{8}-[fF]{4}-[fF]{4}-[fF]{4}-[fF]{12})$
year
integer | null
Intervalo obrigatório: 1993 <= x <= 2100
quarter
integer | null
Intervalo obrigatório: 1 <= x <= 4
include_exhibits
boolean | null
event_types
enum<string>[] | null
Minimum array length: 1
Opções disponíveis:
auditor_change,
non_reliance,
director_officer_change
year_from
integer | null
Intervalo obrigatório: 1993 <= x <= 2100
year_to
integer | null
Intervalo obrigatório: 1993 <= x <= 2100
executive_name
string | null
Required string length: 1 - 200
classification
enum<string> | null
Opções disponíveis:
ipo,
shell_company,
spac,
resale,
other
offering_type
enum<string> | null
Opções disponíveis:
form_d,
form_c,
reg_a
reg_a_form
enum<string> | null
Opções disponíveis:
all,
1-A,
1-K,
1-Z
record_type
enum<string> | null
Opções disponíveis:
actions,
litigation,
administrative,
aaer
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

Evidências normalizadas da SEC com identidade exata do registro/seção e Runs de origem. Campos ausentes ficam como null; metas de oferta diferem de valores vendidos e alegações diferem de resultados. A saída nativa do provedor permanece no Run. Leituras são gratuitas e não retomam a execuçã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:
resolve,
search,
section,
document,
events,
compensation,
board,
audit_fees,
ipo,
private_placements,
enforcement
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

Saída normalizada da SEC completa em JSON, substituindo output. Os links só são renovados dentro dos sete dias de retenção do Run. Os arquivos nativos permanecem em Get Run.

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.