Files and Batch API Workflows

The hardware and bandwidth for this mirror is donated by dogado GmbH, the Webhosting and Full Service-Cloud Provider. Check out our Wordpress Tutorial.
If you wish to report a bug, or if you are interested in having us mirror your free-software or open-source project, please feel free to contact us at mirror[@]dogado.de.

The Batch API is useful when your research task has hundreds or thousands of independent rows: survey coding, abstract screening, entity extraction, document classification, or large-scale summarization.

Prepare JSONL locally

foundry_batch_requests() runs locally. It converts a data frame into the JSON Lines shape expected by the Batch API.

survey <- data.frame(
  id = c("resp-001", "resp-002", "resp-003"),
  response = c(
    "The workshop was clear and practical.",
    "I liked the examples but wanted more time.",
    "The setup instructions were confusing."
  )
)

jsonl <- tempfile(fileext = ".jsonl")

request_file <- foundry_batch_requests(
  survey,
  input = "response",
  path = jsonl,
  model = "gpt-5-nano",
  custom_id = "id",
  body = list(
    instructions = "Classify the response sentiment as positive, neutral, or negative."
  )
)

request_file
#> # A tibble: 1 × 3
#>   path                                   requests endpoint     
#>   <chr>                                     <int> <chr>        
#> 1 /tmp/RtmpTfwV4A/file18126c14463b.jsonl        3 /v1/responses
head(readLines(jsonl), 2)
#> [1] "{\"custom_id\":\"resp-001\",\"method\":\"POST\",\"url\":\"/v1/responses\",\"body\":{\"model\":\"gpt-5-nano\",\"input\":\"The workshop was clear and practical.\",\"instructions\":\"Classify the response sentiment as positive, neutral, or negative.\"}}"     
#> [2] "{\"custom_id\":\"resp-002\",\"method\":\"POST\",\"url\":\"/v1/responses\",\"body\":{\"model\":\"gpt-5-nano\",\"input\":\"I liked the examples but wanted more time.\",\"instructions\":\"Classify the response sentiment as positive, neutral, or negative.\"}}"

The example files use R’s temporary directory and are removed after use. For results you want to keep, choose an explicit output path in your own workflow.

Upload and create a batch

Uploading and batch creation call the Foundry service, so these chunks are not run while building the vignette.

file <- foundry_file_upload(jsonl, purpose = "batch")
unlink(jsonl)

batch <- foundry_batch_create(
  input_file_id = file$file_id,
  endpoint = "/v1/responses"
)

The returned objects include service identifiers, status fields, file sizes, completion windows, and request counts.

Poll and download results

These service calls are not run during rendering. Poll until the batch status is "completed" before downloading its output.

batch <- foundry_batch_get(batch$batch_id)
output_path <- tempfile(fileext = ".jsonl")

foundry_file_download(
  file_id = batch$output_file_id,
  path = output_path
)

Output files are JSONL too. Read a few lines first before parsing a large job:

output_lines <- readLines(output_path, n = 2)
head(output_lines)
unlink(output_path)

Practical advice

Start with 10 to 20 rows and inspect the output before scaling up.
Use stable custom_id values so results join back to your data frame.
Store prompts and schema versions with your analysis code for reproducibility.
Download both output and error files when a batch finishes.

These binaries (installable software) and packages are in development.
They may not be fully stable and should be used with caution. We make no claims about them.
Health stats visible at Monitor.