Senden Sie bis zu 500 Aufgaben in einer Anfrage

Der Batch-Endpoint stellt bis zu 500 Aufgaben mit beliebigen Engines in einem Aufruf in die Warteschlange und meldet das Ergebnis jeder einzelnen.

Was Sie erhalten

• POST /v1/async/task/batch nimmt ein Array mit bis zu 500 Aufgaben an, jede im selben Format wie eine Einzelaufgabe.
• Engines lassen sich frei mischen: Ein Aufruf sendet ein Prompt-Set gleichzeitig an ChatGPT, Gemini und Perplexity.
• results[] meldet jedes Element einzeln: die angelegte Aufgabe oder den Grund, aus dem dieses Element abgelehnt wurde.
• idempotencyKey gilt pro Element, sodass ein wiederholter Batch die bereits angelegten Aufgaben zurückgibt.

So funktioniert es

Ein korrekt aufgebauter Batch antwortet immer mit 200. Jedes Element wird einzeln geprüft: Ein fehlerhafter Prompt erscheint in seinem eigenen results[]-Eintrag, und der Rest des Batches kommt in die Warteschlange. Jede angelegte Aufgabe läuft, endet und wird abgerechnet wie eine Einzelaufgabe, und jede sendet ihren eigenen Webhook.

Mit Batches werden aus Tausenden HTTP-Aufrufen eine Handvoll, und geplante Jobs bleiben schnell und übersichtlich.

Einsatzbereiche

• Senden Sie jeden Morgen ein komplettes Prompt-Set mit einem Aufruf an mehrere Engines.
• Laden Sie eine große Keyword-Liste mit wenigen Anfragen hoch und lassen Sie die Warteschlange sie abarbeiten.

Anfrage senden

Senden Sie bis zu 500 Aufgaben als ein JSON-Array, jede im selben Format wie eine einzelne Aufgabe. Engines und Länder lassen sich in einem Batch frei mischen.

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" }
    }
  ]'

Antwort

Der Aufruf antwortet mit 200 und einem Eintrag pro Aufgabe in der gesendeten Reihenfolge. Die Aufgaben-IDs sind hier gekürzt.

{
  "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

Zählung für den Batch: total, succeeded und failed.

resultsarray

Ein Eintrag pro Aufgabe in der gesendeten Reihenfolge: index, success und die eingereihte task oder error mit Code.

Ergebnis abholen

Die Anfrage liefert sofort die Aufgabe mit status QUEUED. Fragen Sie GET /v1/async/task/{id} ab, bis status COMPLETED oder FAILED ist, oder geben Sie webhook.url an, dann kommt die fertige Aufgabe mit denselben task, credits und response auf Ihrem Server an. Ergebnisse bleiben 24 Stunden nach Abschluss abrufbar.

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

Fehler

Der gesamte Batch antwortet mit 400 VALIDATION_ERROR, wenn der Body ein leeres Array ist oder mehr als 500 Einträge hat, und mit 413 über 8 MiB. In einem Batch passender Größe kommt ein Eintrag über der Parallelität Ihres Plans oder dem Warteschlangenlimit der Engine mit success gleich false und dem Code in error.code zurück, die übrigen werden eingereiht. Senden Sie diese Einträge nach kurzer Wartezeit erneut.

PLAN_CONCURRENCY_LIMITHTTP 429

Ihre wartenden und laufenden Aufgaben haben das Limit des Plans erreicht: 2 im kostenlosen Plan, 10 bei Basic, 25 bei Pro, 50 bei Scale und 100 bei Max. Senden Sie nach Retry-After Sekunden erneut.

QUEUE_BACKPRESSUREHTTP 429

Die Warteschlange der Engine ist gerade voll. Senden Sie nach Retry-After Sekunden erneut.

VALIDATION_ERRORHTTP 400

Ein Feld fehlt oder liegt außerhalb des erlaubten Bereichs. details nennt das Feld.

PAYLOAD_TOO_LARGEHTTP 413

Der Body ist größer als 1 MiB, bei einem Batch größer als 8 MiB.

Preis

Ein Batch kostet die Summe seiner Aufgaben zum Preis der jeweiligen Engine, und jede Aufgabe wird bei Abschluss berechnet.