Map Sume bulk queue results back to spreadsheet rows by item index

How do I know which result belongs to which row?

Queue items carry an index that matches the order of the items array you submitted. If row 17 of your sheet was the 17th item, it is index 16 in a zero-based array. Do not match on timing, because items finish in any order, and do not rely on the run id alone, because items can have none.

Read the queue with GET /v1/format-run-queues/{id}. Each item has index, status, run_id and error. Fetch the child receipt at GET /v1/format-runs/{run_id} for the output and usage.

What about items with no run id?

run_id is null while an item is still queued, and also stays null if the item failed before a child run could start. Such an item has error set instead of a receipt. The queue carries on with the rest, and the queue reaches completed once every item is terminal, so a finished queue with failed items is normal. Check counts.failed and counts.canceled.

For failures that did start, the reason is in the child's receipt, not only on the queue item. A sheet with 100 rows can therefore end with, say, 96 outputs, 3 failed receipts and 1 item that never started, and each of those needs a different cell in your sheet: an output, a reason, and a note that the row can be resubmitted.

import os, requests

API = "https://api.sume.com/v1"
H = {"Authorization": "Bearer " + os.environ["SUME_API_KEY"]}

def results(queue_id, rows):
    q = requests.get(f"{API}/format-run-queues/{queue_id}",
                     headers=H, timeout=30).json()["data"]
    out = []
    for item in q["items"]:
        row = rows[item["index"]]
        if item["run_id"] is None:
            out.append({**row, "status": item["status"],
                        "error": item["error"], "output": None})
            continue
        run = requests.get(f"{API}/format-runs/{item['run_id']}",
                           headers=H, timeout=30).json()["data"]
        out.append({**row, "status": run["status"],
                    "error": None, "output": run.get("output")})
    return out

How do I keep this reliable?

• Keep the submitted rows list in memory or in a file, keyed by index, until the queue is terminal.
• Write status and error back to the sheet for every row, including the ones with no run.
• Retry only the failed rows as a new queue with new keys; a replayed key with the same payload returns the old queue.
• If you chunked a large sheet, add the chunk's starting row to index to get the sheet row.