Skip to contents

Submit an extract request via the IPUMS API and return an ipums_extract object containing the extract definition with a newly-assigned extract request number.

Learn more about the IPUMS API in vignette("ipums-api").


submit_extract(extract, api_key = Sys.getenv("IPUMS_API_KEY"))



An ipums_extract object.


API key associated with your user account. Defaults to the value of the IPUMS_API_KEY environment variable. See set_ipums_api_key().


An ipums_extract object containing the extract definition and newly-assigned extract number of the submitted extract.

Note that some unspecified extract fields may be populated with default values and therefore change slightly upon submission.

See also

wait_for_extract() to wait for an extract to finish processing.

get_extract_info() and is_extract_ready() to check the status of an extract request.

download_extract() to download an extract's data files.


my_extract <- define_extract_cps(
  description = "2018-2019 CPS Data",
  samples = c("cps2018_05s", "cps2019_05s"),
  variables = c("SEX", "AGE", "YEAR")

if (FALSE) {
# Store your submitted extract request to obtain the extract number
submitted_extract <- submit_extract(my_extract)


# This is useful for checking the extract request status

# You can always get the latest status, even if you forget to store the
# submitted extract request object
submitted_extract <- get_last_extract_info("cps")

# You can also check if submitted extract is ready

# Or have R check periodically and download when ready
downloadable_extract <- wait_for_extract(submitted_extract)