Files and Batch API Workflows

In foundryR: Data Frame Workflows for 'Microsoft Foundry'

fixture_dir <- "files-batches"
recording <- nzchar(Sys.getenv("FOUNDRY_RECORD_DOCS"))
have_fixtures <- dir.exists(fixture_dir) && length(list.files(fixture_dir)) > 0
run_api <- requireNamespace("httptest2", quietly = TRUE) &&
  (recording || have_fixtures)

# Attach foundryR before start_vignette(): httptest2 only sources the package's
# inst/httptest2/start-vignette.R (which sets replay placeholders) from attached
# packages.
library(foundryR)

if (run_api) {
  httptest2::start_vignette(fixture_dir)
}

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  eval = run_api
)

library(foundryR)

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
head(readLines(jsonl), 2)

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.

unlink(jsonl)
if (run_api) {
  httptest2::end_vignette()
}

foundryR documentation built on Sept. 25, 2026, 1:10 a.m.