Administer a panel asynchronously through the batch API

Submits one request per persona and item to a provider's batch API and returns a job handle. Use panel_batch_status() to inspect the job and panel_batch_fetch() to retrieve completed results. Provider services determine prices and completion times.

Usage

panel_batch_submit(
  panel,
  instrument,
  config,
  state_path = NULL,
  max_calls = 5000L,
  confirm = FALSE
)

Arguments

panel

A panel_from_margins() / panel_from_data() / panel_from_personas() result.

instrument

A panel_instrument().

config

An LLMR::llm_config() for a generative model on a provider with a supported batch API (OpenAI, Groq, Anthropic, Gemini).

state_path

Optional path; when given the job is also saved there as RDS so it can be fetched from another session.

max_calls

Integer. If the run would make more than this many calls, it stops unless confirm = TRUE. Default 5000.

confirm

Logical. Set TRUE to proceed past max_calls.

Value

A panel_batch_job handle.

Details

All personas are administered under one config (one model). The handle carries the survey prompts and rendered persona text. When state_path is supplied, the API key must be referenced through an environment variable so its value is not written to the saved state.

See also

panel_batch_fetch(), panel_batch_status(), panel_administer().

Examples

if (FALSE) { # \dontrun{
panel <- panel_from_margins(list(party = c(left = .5, right = .5)), n = 200)
instrument <- panel_instrument(item_likert("wk4", "A four-day work week helps."))
cfg <- LLMR::llm_config("groq", "openai/gpt-oss-20b")
job <- panel_batch_submit(panel, instrument, cfg, state_path = "panel_job.rds")
# ... later:
resp <- panel_batch_fetch(job)
} # }