Written and maintained by CASRAI Editorial Board
Published
On this page
httr is an R package for sending HTTP requests and reading the responses, used to pull data from web APIs into an analysis. It wraps the curl package and provides GET(), POST() and the other HTTP verbs, a standard response object, cookie handling and OAuth 1.0/2.0 support. The httr project now describes the package as superseded: only changes needed to keep it on CRAN will be made, and its documentation recommends httr2 for new code. Existing scripts that use httr still run; this page shows how to use it and when to move on.
Who this is for: researchers and analysts who need to call a web API from R, or who inherited a script that loads httr. After reading you should be able to install the package, make a GET request with query parameters, check the status, parse the body, and decide whether to migrate.
What httr is used for in research
Many public data services (repositories, registries, bibliographic indexes, statistical agencies) are reached over HTTP. httr lets an R script request a URL, pass query parameters, and receive the response as an object holding the status, headers and body. The package documentation lists these capabilities: connection sharing, cookie handling, a standard response object, and OAuth 1.0 and 2.0 for services that require authorisation.
A scripted request is also a reproducibility aid: the exact URL, parameters and parse step live in code rather than in a manual download. See computational reproducibility and renv for locking the package version a script was written against.
Current status: httr or httr2?
The httr site (version 1.4.9 on CRAN, published 2026-09-01) states that httr is no longer recommended for new code and recommends httr2. The httr2 site presents itself as a modern, pipeable HTTP client that adds explicit request objects, built-in rate limiting and retry tooling, and an overhauled OAuth system, and says a single req_perform() replaces calls such as httr::GET(), httr::POST() and httr::DELETE().
- Keep httr when maintaining an existing script or package that already works and whose dependencies are pinned.
- Use httr2 when starting new code, or when you need built-in retries and rate limiting.
Install or access
httr is distributed on CRAN under an MIT licence. Version 1.4.9 depends on R (>= 3.6) and imports curl (>= 5.1.0), jsonlite, mime, openssl (>= 0.8) and R6. The maintainer listed on CRAN is Hadley Wickham.
install.packages("httr")
library(httr)
The project documentation gives this command for the development version from GitHub:
pak::pak("r-lib/httr")
For repository choices and package-installation errors, see How to Install R Packages (CRAN, Bioconductor, GitHub).
Step by step: request an API, check the status, parse the JSON
The httr reference pages use the test service httpbin.org in their examples; the steps below do the same so that they can be run without an account.
- Send the request.
GET(url = NULL, config = list(), ..., handle = NULL)returns a response object. Named query parameters go inquery:r <- GET("https://httpbin.org/get", query = list(topic = "cohort", page = 1)) - Set a timeout and identify your script.
timeout(seconds)sets how many seconds to wait for a response before giving up (it cannot be less than 1 ms).user_agent(agent)overrides the default user agent with a string you supply. Both are passed as config arguments:r <- GET("https://httpbin.org/get", query = list(topic = "cohort", page = 1), timeout(10), user_agent("my-lab-analysis-script")) - Stop on HTTP errors.
stop_for_status(x, task = NULL)converts an HTTP error into an R error and returns the response invisibly when the request succeeded. The reference states it should always be used when creating requests inside a function. The optionaltasktext is appended to the message after “Failed to”:stop_for_status(r, task = "download test data") - Read the body.
content(x, as = NULL, type = NULL, encoding = NULL, ...)returns the body. Withasleft as NULL, it picks an output based on the content type, so a JSON response comes back as an R object parsed byjsonlite::fromJSON():parsed <- content(r) # parsed R object for JSON txt <- content(r, "text") # one UTF-8 string raw_bytes <- content(r, "raw") # raw vector - Send data with POST. The reference example posts a list as the body:
POST("http://httpbin.org/post", body = list(a = 1, b = 2)), then callscontent()on the result.
For data you will analyse, convert the parsed list to a data frame in the usual way (see dataframe in R programming).
Output and how to read it
The response object bundles the status, headers and body; content() is the usual way in. Its documented output types are:
as = |
Returns |
|---|---|
"raw" |
A raw vector of the bytes from the server |
"text" |
A character vector of length 1, always re-encoded to UTF-8 (NA if re-encoding fails) |
"parsed" |
A parsed R object, chosen from the response MIME type |
When as = "parsed" (or left NULL), content() maps MIME types to parsers as follows:
| MIME type | Parser |
|---|---|
| application/json | jsonlite::fromJSON() |
| text/html | xml2::read_html() |
| text/xml | xml2::read_xml() |
| text/csv | readr::read_csv() |
| text/tab-separated-values | readr::read_tsv() |
| application/x-www-form-urlencoded | parse_query |
| image/jpeg | jpeg::readJPEG() |
| image/png | png::readPNG() |
The documentation calls parsed output “provided as a convenience only”. For other types use as = "text" and parse the string yourself. For JSON versus XML responses, see JSON vs XML for research data and APIs.
Troubleshooting
The script stops with an HTTP error
That is stop_for_status() doing its job: an HTTP error response is raised as an R error. Check the URL and query parameters, and pass task so that the message names what failed. warn_for_status() and message_for_status() take the same arguments and raise a warning or print a message instead.
Text comes back garbled
If the server reports the wrong character set, content() accepts an encoding argument that overrides the charset for text and parsed output. The documented default is Latin1 (ISO-8859-1).
The server returns a type httr does not parse
Use content(r, "text") and parse the string. Use type to override the MIME type the server reports if it labels the body incorrectly.
The request hangs
Add timeout(seconds) to the call, as in step 2.
Parsing inside your own package
The reference warns that inside a package you should not rely on as = "parsed": check that the MIME type is what you expect, then parse it yourself, so that failures are clearer if the API changes.
Free alternatives
| Package | What its documentation says | Install |
|---|---|---|
| httr2 | Successor to httr; pipeable API, explicit request objects, built-in rate limiting and retries, overhauled OAuth; req_perform() replaces the separate verb functions |
install.packages("httr2") |
| curl | The package httr wraps (httr imports curl >= 5.1.0); httr2 is also built on it | install.packages("curl") |
| httr (this page) | Superseded; changes limited to keeping it on CRAN | install.packages("httr") |
For wider tool choices see free statistical software for research.
FAQ
What is the httr package in R?
An R package that wraps curl to send HTTP requests to web APIs and return a standard response object, with cookie handling and OAuth 1.0/2.0 support. Source: httr.r-lib.org, read 2026-11-07.
Is httr deprecated?
The project calls it superseded, not removed: only changes necessary to keep it on CRAN will be made, and httr2 is recommended for new code. Version 1.4.9 was published on CRAN on 2026-09-01.
How do I install httr?
Run install.packages("httr"), then library(httr).
How do I get JSON from an API with httr?
Call GET(), check it with stop_for_status(), then call content(); a JSON response is parsed with jsonlite::fromJSON().
Sources
- httr package site (read 2026-11-07)
- httr reference pages: GET, content, stop_for_status, user_agent, timeout (read 2026-11-07)
- httr on CRAN (read 2026-11-07)
- httr2 package site (read 2026-11-07)







