Pular para o conteúdo principal
POST
Executar um endpoint
  • 200: o Run foi concluído. Verifique seu status, a resposta do provedor de dados e a cobrança.
  • 202: um Run assíncrono ainda está em andamento. Use Get a Run para verificar o resultado.
Um Run concluído pode conter um erro do provedor de dados. Use o mesmo Idempotency-Key e os mesmos parâmetros de execução ao tentar novamente.

Cabeçalhos

idempotency-key
string
obrigatório

Gere um valor exclusivo para cada execução pretendida (recomenda-se um UUID). Tente novamente com a mesma chave e os mesmos parâmetros de execução para recuperar o Run original sem uma segunda cobrança. Alterar os parâmetros de execução usando a mesma chave retorna 409; alterar task_id ou metadata não atualiza o Run original.

Minimum string length: 1

Corpo

application/json
provider
string
obrigatório
Pattern: ^[a-z0-9][a-z0-9-]*$
endpoint
string
obrigatório
Pattern: ^\/.+$
input
object

Entrada nativa do provedor de dados. Construa-a a partir de input_schema retornado por Inspect.

endpoint_version
integer | null

Selecione uma versão compatível ou omita-a para usar o padrão. Atualizações compatíveis mantêm a versão; versões indisponíveis ou descontinuadas retornam 409. Uma versão não fixa o preço: novos Runs usam o preço no momento da admissão, e Runs aceitos o mantêm até a liquidação.

Intervalo obrigatório: x > 0
task_id
string | null

A tarefa à qual este Run pertence, obtida de uma resposta de pesquisa do catálogo. Apenas agrupamento: nunca afeta o roteamento, o preço ou a idempotência.

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

um Run terminal: COMPLETED, FAILED ou STOPPED

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, inclusive respostas não 2xx. FAILED: consulte failure. STOPPED: interrompido antes do envio. 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 o status é FAILED.

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

Não nulo somente quando o status é COMPLETED.

  • Para respostas 2xx, output contém JSON nativo do provedor de dados (qualquer formato) 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.

Campos sensíveis são removidos de ambos os corpos.

charge_usd
string | null
obrigatório

Cobrança final como uma string decimal exata em USD. Nulo enquanto QUEUED ou RUNNING. Um Run FAILED pode ter uma cobrança diferente de zero conforme o preço do endpoint.

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

Cláusula de preço usada para calcular a cobrança. Nulo antes da liquidação ou quando não houve tentativa com o provedor de dados.

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 envio.

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

Quando uma parada foi solicitada. O Run ainda pode continuar se o dispatch já tiver começado.

created_at
string<date-time>
obrigatório

timestamp UTC ISO-8601

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

timestamp UTC ISO-8601

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

timestamp UTC ISO-8601

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

Seus campos de rastreamento armazenados. Use-os para filtrar Runs. 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.