Submit and retrieve

Batch rules

• The request body is a JSON array containing 1–50 entries.
• Each entry contains question, platformCode, and optional options, webhookUrl, and clientReference.
• Each entry contains exactly one question and one platform.
• Every entry has an independent taskId, result, charge, and notification.
• Identical entries are accepted and are not merged.
• If any entry is invalid, the whole request is rejected.

Idempotency-Key only prevents a retried HTTP request from creating another set of tasks. The same key and body return the original task IDs; the same key with another body returns HTTP 409.

States

State	Meaning
pending	Accepted and waiting
processing	In progress
completed	Completed
failed	Not completed
stopped	Stopped

Increase polling intervals gradually, for example 2, 4, and 8 seconds, capped at 30 seconds. You may also use completion notifications.

Answer and rich media

After completion, content contains the answer. If the platform returns products, videos, images, documents, or files, content also contains display-ready Markdown cards with type labels. The same data is available in structured products, videos, and media arrays.

All three arrays share one global position sequence. Merge the arrays and sort by position to restore the display order. For a product click, prefer products[].url and inspect urlType: web opens in a browser, while app_deep_link requires a compatible app and device. If opening a deep link fails, try fallbackUrl when present. Optional fields depend on the data returned for that task.

The task object in a completion notification uses the same result structure. If a large result is omitted, retrieve it with taskId.

Result content is retained for 7 days by default. After expiry, taskId, state, and charges remain available and expired is true.