Documentation Index

Fetch the complete documentation index at: https://docs.moda.app/llms.txt

Use this file to discover all available pages before exploring further.

​

Bulk variants

​

The single biggest gotcha — concurrency caps

​

Pattern A — fan out start_design_task (N independent designs)

Kicking off 10 LinkedIn ads, one per persona. I’ll run them in batches of 3 (concurrency cap) and post each canvas URL as soon as it’s ready — you can open them while the others are still rendering.

personas = ["CFOs", "CTOs", "heads of ops", ...]   # the user-provided list
dimensions = dict(format_category="social", format_width=1080, format_height=1080)
window = whoami_response.get("concurrency_cap", 3)   # use whoami's value; fall back to 3 if unknown

def build_prompt(persona):
    return f"""
      LinkedIn ad for our automation tool, tailored to {persona}.
      Lead with the single pain point this persona feels most acutely
      and the one metric they measure success on. Bold typography, clean
      layout, one CTA.
    """

in_flight = {}          # persona -> task handle
done = {}               # persona -> terminal status
queue = list(personas)  # to-do

# 1. Seed the window
while len(in_flight) < window and queue:
    p = queue.pop(0)
    in_flight[p] = start_design_task(prompt=build_prompt(p), **dimensions)
    # tell the user immediately — canvas_url is in the queued response
    post(f"Started {p}: {in_flight[p]['canvas_url']}")

# 2. Drain + refill
while in_flight:
    # poll the whole pool in one call — cheaper than N get_task_status calls
    pool = list_tasks(status="running", limit=window * 2)
    pool_ids = {t["task_id"] for t in pool["tasks"]}

    for persona, handle in list(in_flight.items()):
        if handle["task_id"] in pool_ids:
            continue   # still running

        # terminal — fetch full status, file under done, slot in next
        s = get_task_status(task_id=handle["task_id"])
        done[persona] = s
        del in_flight[persona]
        post_done(persona, s)   # deliver this one as it finishes

        if queue:
            p = queue.pop(0)
            in_flight[p] = start_design_task(prompt=build_prompt(p), **dimensions)
            post(f"Started {p}: {in_flight[p]['canvas_url']}")

    sleep(3)   # respect retry_after_seconds from any poll

• list_tasks(status="running", ...) is one RPC for the whole pool. Beats get_task_status × N per tick.
• Post each canvas URL when the task is queued, not when it finishes. The user can open it immediately — they’ll see the agent’s progress in the canvas itself.
• Deliver each result as it terminates. Bulk feels much faster when 1/10 done shows up in 90s than when all 10 land together at 8 min.
• post_done(persona, s) surfaces s["error"] if the task failed. Don’t let one bad persona block the rest.

​

What goes in the prompt vs the parameters

• Per-persona detail belongs in the prompt — rewrite the pain point, metric, and CTA for each. Don’t just template {persona} into a generic sentence.
• Dimensions and format_category stay constant across the batch. They’re parameters.
• One brand kit for all unless the user says otherwise. Omit brand_kit_id so each task picks up the team default. Don’t fetch the kit per task — fetch once before the loop.

​

Pattern B — fan out start_design_task with template_canvas_id (N variants of a source canvas)

• Same brand kit as the source → content-only remix (preserve design, swap content)
• Different brand_kit_id → full rebrand (rework colors, fonts, copy, imagery)
• skip_brand_kit=True → no forced skill; the curator decides

source_id = "cvs_…"               # the flyer canvas the user pointed at
resellers = [...]                  # 5 items, each with optional brand_kit_id for per-client rebrand
window = 3

queue = list(resellers)
in_flight = {}

def build_prompt(reseller):
    return f"""
      Customize this flyer for {reseller['name']}:
        - replace the headline price with {reseller['price']}
        - update the contact strip with {reseller['phone']} / {reseller['email']}
    """

while len(in_flight) < window and queue:
    r = queue.pop(0)
    in_flight[r["name"]] = start_design_task(
      template_canvas_id=source_id,
      prompt=build_prompt(r),
      brand_kit_id=r.get("brand_kit_id"),   # per-client brand if rebranding; omit for same-brand fill
      canvas_name=f"Flyer — {r['name']}",
      # wait defaults to False on start_design_task — handle returned immediately
    )
    post(f"Started {r['name']}: {in_flight[r['name']]['canvas_url']}")

# Same drain + refill loop as Pattern A

• canvas_id edits the original. Five resellers, one canvas — the last one wins. The user loses their template.
• template_canvas_id duplicates first. Original stays clean; you get N independent copies.
• Layout / structure carry forward automatically. You only specify what changes in the prompt.
• Per-variant brand swap is first-class. Pass a different brand_kit_id per call to produce the same design rebranded for each client.

​

When to use remix_design instead

​

Recovery: a task in the batch fails

• Rate limit (AgentJobRateLimitError text in error) — your window is too wide. Drop it by one, retry that persona/reseller.
• Billing (out of credits) — stop the whole batch. Tell the user; the remaining queued items would all fail the same way.
• Validation — bad prompt or parameters for that one task. Skip it, continue with the rest.
• Upstream model error — retry that one task once. If it fails again, skip.

​

Aborting a bulk run mid-flight

​

See also

• ../references/gotchas.md — wait asymmetry, concurrency caps, format defaults, carousel cap, not_ready retry, and the rest of the silent-fail set
• ../references/tools.md — full signatures for start_design_task, remix_design, list_tasks, cancel_task