Saltar al contenido principal
POST
Ejecutar un Endpoint
  • 200: el Run ha terminado. Comprueba su estado, la respuesta del proveedor de datos y el cargo.
  • 202: un Run asíncrono sigue en curso. Usa Get a Run para comprobar su resultado.
Un Run terminado puede contener un error del proveedor de datos. Usa el mismo Idempotency-Key y los mismos parámetros de ejecución al reintentar.

Encabezados

idempotency-key
string
requerido

Genere un valor único para cada ejecución prevista (se recomienda un UUID). Reintente con la misma clave y los mismos parámetros de ejecución para recuperar el Run original sin un segundo cargo. Cambiar los parámetros de ejecución con la misma clave devuelve 409; cambiar task_id o metadata no actualiza el Run original.

Minimum string length: 1

Cuerpo

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

Entrada nativa del proveedor de datos. Constrúyela a partir de input_schema, devuelto por Inspect.

endpoint_version
integer | null

Selecciona una versión compatible u omítela para usar la predeterminada. Las actualizaciones compatibles conservan la versión; las versiones no disponibles o retiradas devuelven 409. Una versión no fija el Price: los Runs nuevos usan el Price vigente en el momento de admisión y los Runs aceptados lo conservan hasta la liquidación.

Rango requerido: x > 0
task_id
string | null

La tarea a la que pertenece este Run, obtenida de una respuesta de búsqueda del catálogo. Solo sirve para agrupar: nunca afecta al enrutamiento, el precio ni la idempotencia.

metadata

Campos de seguimiento opcionales, devueltos en el Run y disponibles como filtros. Nunca se envían al proveedor de datos ni afectan al enrutamiento, Price o la idempotencia.

  • Hasta 20 claves: letras minúsculas, dígitos y guiones bajos; deben comenzar con una letra y tener como máximo 40 caracteres.
  • Valores: cadenas de 1–500 caracteres.
  • user_id: el ID opaco de tu usuario final, nunca su dirección de correo electrónico ni su nombre.

Las entradas no válidas se descartan por completo, no se truncan. La solicitud continúa y el Run devuelve los campos que se almacenaron.

Respuesta

un Run terminal: COMPLETED, FAILED o STOPPED

id
string
requerido
run_url
string
requerido

Abra este Run en la consola. Requiere pertenecer a un Workspace.

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

QUEUED o RUNNING: todavía está en curso. COMPLETED: hay una respuesta del proveedor de datos disponible, incluidas las respuestas que no sean 2xx. FAILED: consulta failure. STOPPED: detenido antes del envío. Lea charge_usd por separado del estado.

Opciones disponibles:
QUEUED,
RUNNING,
COMPLETED,
FAILED,
STOPPED
failure
object | null
requerido

Motivo por el que falló el Run. Solo es distinto de null cuando el estado es FAILED.

input
object
requerido
output
any
requerido
provider_response
object | null
requerido

Solo es distinto de null cuando el estado es COMPLETED.

  • Para respuestas 2xx, output contiene JSON nativo del proveedor de datos (con cualquier estructura) o null si el cuerpo está vacío.
  • Para respuestas que no sean 2xx, error contiene el cuerpo del error del proveedor de datos y output es null.

Los campos sensibles se eliminan de ambos cuerpos.

charge_usd
string | null
requerido

Cargo final como cadena decimal exacta en USD. Es null mientras el estado sea QUEUED o RUNNING. Un Run FAILED puede tener un cargo distinto de cero según el Price del endpoint.

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

Cláusula de Price utilizada para calcular el cargo. Es null antes de la liquidación o cuando no se intentó contactar con ningún proveedor de datos.

stoppable
boolean
requerido

Indica si actualmente se puede aceptar una solicitud de detención. Esto no garantiza que el Run pueda detenerse antes del envío.

stop_requested_at
string<date-time> | null
requerido

Cuándo se solicitó la detención. El Run aún puede continuar si el dispatch ya había comenzado.

created_at
string<date-time>
requerido

Marca de tiempo UTC ISO-8601

started_at
string<date-time> | null
requerido

Marca de tiempo UTC ISO-8601

completed_at
string<date-time> | null
requerido

Marca de tiempo UTC ISO-8601

task_id
string | null
requerido
metadata
object
requerido

Tus campos de seguimiento almacenados. Úsalos para filtrar Runs. Nunca se envían al proveedor de datos ni afectan al enrutamiento, Price o la idempotencia.

  • Hasta 20 claves: letras minúsculas, dígitos y guiones bajos; deben comenzar con una letra y tener como máximo 40 caracteres.
  • Valores: cadenas de 1–500 caracteres.
  • user_id: el ID opaco de tu usuario final, nunca su dirección de correo electrónico ni su nombre.