Envía hasta 500 tareas en una sola solicitud

El endpoint de lotes pone en cola hasta 500 tareas con cualquier combinación de motores en una sola llamada e informa del resultado de cada una.

Qué obtienes

• POST /v1/async/task/batch acepta un array de hasta 500 tareas, cada una con el mismo formato que una tarea individual.
• Los motores se combinan libremente: una sola llamada envía un conjunto de prompts a ChatGPT, Gemini y Perplexity a la vez.
• results[] informa de cada elemento por separado: la tarea creada o el motivo por el que se rechazó ese elemento.
• idempotencyKey funciona por elemento, así que un lote reenviado devuelve las tareas que ya había creado.

Cómo funciona

Un lote bien formado siempre responde 200. Cada elemento se valida por separado, de modo que un prompt mal formado aparece en su propia entrada de results[] mientras el resto del lote entra en la cola. Cada tarea creada se ejecuta, se completa y se cobra igual que una tarea individual, y cada una envía su propio webhook.

Con los lotes, miles de llamadas HTTP se reducen a unas pocas, y los trabajos programados son más rápidos y sencillos.

Para qué sirve

• Envía cada mañana un conjunto completo de prompts a varios motores con una sola llamada.
• Carga una lista grande de palabras clave en pocas solicitudes y deja que la cola la procese.

Envía la solicitud

Envía hasta 500 tareas en un solo array JSON, cada una con la misma forma que una tarea individual. Motores y países se combinan libremente en un mismo lote.

curl -X POST https://api.querying.ai/v1/async/task/batch \
  -H "Authorization: Bearer $QUERYING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "taskType": "CHATGPT",
      "payload": { "prompt": "best CRM for startups", "country": "US" }
    },
    {
      "taskType": "GEMINI",
      "payload": { "prompt": "best CRM for startups", "country": "US" }
    },
    {
      "taskType": "PERPLEXITY",
      "payload": { "prompt": "best CRM for startups", "country": "US" }
    }
  ]'

Respuesta

La llamada responde 200 con una entrada por tarea, en el orden en que las enviaste. Aquí los ID de tarea van abreviados.

{
  "success": true,
  "summary": { "total": 3, "succeeded": 3, "failed": 0 },
  "results": [
    {
      "success": true,
      "index": 0,
      "task": {
        "id": "…",
        "taskType": "CHATGPT",
        "status": "QUEUED",
        "priority": 1,
        "createdAt": "…"
      },
      "credits": { "creditsToCharge": 0, "creditsCharged": 0 }
    },
    {
      "success": true,
      "index": 1,
      "task": {
        "id": "…",
        "taskType": "GEMINI",
        "status": "QUEUED",
        "priority": 1,
        "createdAt": "…"
      },
      "credits": { "creditsToCharge": 0, "creditsCharged": 0 }
    },
    {
      "success": true,
      "index": 2,
      "task": {
        "id": "…",
        "taskType": "PERPLEXITY",
        "status": "QUEUED",
        "priority": 1,
        "createdAt": "…"
      },
      "credits": { "creditsToCharge": 0, "creditsCharged": 0 }
    }
  ]
}

summaryobject

Recuento del lote: total, succeeded y failed.

resultsarray

Una entrada por tarea, en el orden en que las enviaste: index, success y la task en cola, o error con su código.

Recibe el resultado

La solicitud devuelve la tarea al instante con status QUEUED. Consulta GET /v1/async/task/{id} hasta que status sea COMPLETED o FAILED, o añade webhook.url y la tarea terminada llega a tu servidor con los mismos task, credits y response. Los resultados siguen disponibles 24 horas después de terminar la tarea.

curl https://api.querying.ai/v1/async/task/$TASK_ID \
  -H "Authorization: Bearer $QUERYING_API_KEY"

Errores

El lote completo responde 400 VALIDATION_ERROR si el cuerpo es un array vacío o supera 500 elementos, y 413 por encima de 8 MiB. En un lote de tamaño correcto, un elemento que supera la concurrencia de tu plan o el límite de cola del motor vuelve con success en false y su código en error.code, y el resto entra en la cola. Reenvía esos elementos tras una breve espera.

PLAN_CONCURRENCY_LIMITHTTP 429

Tus tareas en cola y en curso llegaron al límite del plan: 2 en el plan gratuito, 10 en Basic, 25 en Pro, 50 en Scale y 100 en Max. Vuelve a enviar tras Retry-After segundos.

QUEUE_BACKPRESSUREHTTP 429

La cola del motor está llena por un momento. Vuelve a enviar tras Retry-After segundos.

VALIDATION_ERRORHTTP 400

Falta un campo o su valor está fuera de rango. details indica el campo.

PAYLOAD_TOO_LARGEHTTP 413

El cuerpo supera 1 MiB, u 8 MiB en un lote.

Precio

Un lote cuesta la suma de sus tareas al precio de cada motor, y cada tarea se cobra cuando se completa.