Guide · Open source

How to use got: install and make HTTP requests in Node.js

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

Got is a JavaScript library that lets Node.js programs send HTTP requests to web servers and APIs. It takes care of common chores such as JSON bodies, retries on failure, timeouts and redirects, so you write less boilerplate. This guide shows how to install it, send a JSON request, and find the parts of the documentation you will need next.

gotsindresorhus/got · ★ 15k · MIT Install options & downloads

Quick start

1Check your setup. Confirm you have Node.js and an ESM-based project. If your project uses CommonJS, convert it to ESM first.
2Install got. Run npm install got in your project folder.
3Import got. Use import got from 'got'; in your ESM file.
4Send a request. Call got.get or got.post with a URL and options such as json.
5Read the response. Add .json() to the request to get the parsed body as a Promise.
6Tune retries and timeouts. Keep the default retry behaviour or set options.retry.limit to 0, then read the timeout documentation for advanced settings.

Check whether got fits your project

Got is built for server-side Node.js code that calls web APIs. The package is native ESM and has no CommonJS export, so if your project uses CommonJS you will need to convert it to ESM first.

The README points readers to Ky, a related library by the same author, for most users who need browser support or a smaller package. Got's comparison table marks browser support as unsupported.

Good fit: Node.js backends calling web APIs
Good fit: projects that want built-in retries, advanced timeouts or pagination helpers
Not a fit: browser-only projects; the README suggests Ky instead
Not a fit: anyone who needs Got v11, which the README says is no longer maintained

Install got with npm

You need Node.js installed. Install the package from npm with the command below, run in your project folder.

npm install got

Send a JSON POST request

Got has a dedicated option for JSON payloads. The promise also exposes a .json() function that returns a Promise of the parsed result. The example below posts a small object to httpbin.org and logs the response data.

For advanced JSON usage, the README points to the parseJson and stringifyJson options in the options documentation.

import got from 'got';

const {data} = await got.post('https://httpbin.org/anything', {
	json: {
		hello: 'world'
	}
}).json();

console.log(data);
//=> {"hello": "world"}

Understand retries and timeouts

By default, Got retries on failure. The README says you can disable this by setting options.retry.limit to 0. Got also has advanced timeout handling, documented separately in the timeout and retry guides.

Retries on failure are on by default
Set options.retry.limit to 0 to turn retries off
Advanced timeout handling is covered in the timeout documentation

Know what else Got offers

The README lists features across several areas. Use this list to find the documentation page for what you need.

Promise API, Stream API and Pagination API
HTTP/2 support and Advanced HTTPS API
Hooks, instances, progress events and plugins
RFC 7234 compliant caching, proxy support and Unix Domain Sockets
TypeScript support and diagnostics channel

Use plugins for common services

The README lists Got plugins built on top of the library. Examples include gh-got for the GitHub API, gl-got for the GitLab API, and got-scraping, a wrapper designed for web scraping. Each plugin is a separate project with its own README.

gh-got: wrapper for the GitHub API
gl-got: wrapper for the GitLab API
got-scraping: wrapper for web scraping
got-ssrf: wrapper that protects server-side requests against SSRF attacks

What people use it for

Calling a REST API from a Node.js backend and parsing the JSON response
Posting JSON data to an external service
Calling the GitHub or GitLab APIs through the gh-got or gl-got wrappers
Adding retries and timeouts to outgoing requests in server code

Frequently asked questions

Is got free to use?

Got is released under the MIT licence, as listed on its project page. The MIT licence is a permissive open-source licence, so check its terms for your own use case.

Does got work with CommonJS?

No. The README says the package is native ESM and no longer provides a CommonJS export. The README suggests converting your project to ESM, and says not to open issues about CommonJS or ESM questions.

Can I use got in the browser?

The comparison table in the README marks browser support as unsupported for got. The README suggests Ky instead, a related library by the same author that works in the browser and is built on Fetch.

What are the alternatives to got?

The README compares got with node-fetch, ky, axios and superagent. Ky is the one the README recommends for most users who need browser support or a smaller package.

How do I turn off retries in got?

By default got retries on failure. The README says to set options.retry.limit to 0 to disable this.

Where do I get help with got?

The README says support questions should be asked in the project's GitHub discussions page.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Got suits Node.js developers who call web APIs from server code and want retries, advanced timeouts and JSON handling built in. If you need browser support, want a smaller package, or still use CommonJS, the README points you to Ky or a different library.

Install options & downloads