Batches

Provider batch APIs run many requests at a lower price, but take minutes to hours. aiBatches from better-supabase/ai-sdk/batches starts a batch with experimental_startBatch, records it in the AI providers block, and a job polls it until the results are stored in ai_batch_items.

import "server-only";

import { aiBatches } from "better-supabase/ai-sdk/batches";

export const batchesFor = (supabase: SupabaseClient) =>
  aiBatches({ providers: providersFor(supabase) });

const batch = await batchesFor(supabase)
  .start(
    { organizationId, userId },
    {
      requests: tickets.map((ticket) => ({
        id: ticket.id,
        type: "text",
        model: "openai/gpt-5-mini",
        prompt: `Summarize: ${ticket.body}`,
      })),
      metadata: { job: "ticket-summaries" },
    },
  )
  .orThrow();

start calls the provider, then records the batch as the caller, so a member needs ai.create in the organization. metadata stays in the row and never goes to the provider. A provider error is a network error with the hint AI_BATCH_PROVIDER.

The poll jobCopy Anchor Link

Schedule pollJob every minute through the jobs block. Each run claims the batches whose next poll is due, so two workers never poll the same batch:

const batches = aiBatches({
  providers: createAiProviders({ transport: service, service, schema: "api" }),
  onDone: (batch) => notify(batch.userId, "Your summaries are ready"),
});

handlers: {
  ai_batch_poll: batches.pollJob();
}

A poll that fails keeps the batch due and notes the error on the row; the next run tries again. onItem(item, batch) changes what is stored for a result, for example to move a generated image to Storage and keep its path.

Reading resultsCopy Anchor Link

const status = await batches.status(batchId).orThrow();
const page = await batches
  .results(batchId, { cursor: lastRequestId, limit: 100 })
  .orThrow();

Both read as the caller: a member sees the batches they started, and ai.admin sees every batch in the organization. cancel(batch) asks the provider to cancel and stores the new status.