> **For coding agents and LLMs:** This is one Social Fetch marketing page (markdown export). For API orientation start with [`/llms.txt`](https://www.socialfetch.dev/llms.txt); for auth and crawl rules use [`/agents.txt`](https://www.socialfetch.dev/agents.txt); for every operation use [`/llms-endpoints.txt`](https://www.socialfetch.dev/llms-endpoints.txt). ## This page - **On-site (HTML):** - **Markdown (.mdx) URL:** --- # npm API. Packages, downloads and provenance as JSON. Get a package, one version, its full version list, download counts, advisories, provenance attestations, dependents, search results, users and orgs. Name the package and read typed JSON. - Packages + owners - Downloads + advisories - 1 credit per package name Social Fetch exposes eighteen routes under `/v1/npm`. Package routes cover one package with its latest version, every dist-tag and last week's downloads; the full registry document with timestamps, README, version list and the extra package facts; the version list newest first; and one version document by exact version or dist-tag. Write `express`, `lodash.merge` or `@types/node` as it appears in npm; names are case-sensitive. Download routes cover a package total or one row per day, last week's downloads for every version, and a batch of up to 128 names in one call. Security routes cover advisories for one version or every version, and the publish and SLSA provenance attestations behind a version, decoded into fields. Community routes cover packages that depend on a package, registry search, users, orgs, and their package lists. Registry routes cover package names in key order, the change feed from a sequence, and the recent-updates feed. Every response uses the `{ data, meta }` envelope: single lookups set `data.lookupStatus` to `found` or `not_found`, lists expose `page.nextCursor` and `page.hasMore`, and `meta.creditsCharged` is what the request cost. ## What you can get - One package with `data.package`, `data.distTags`, `data.latestVersion` and `data.downloads`. - The full registry document with `starCount`, `readme`, `versionCount` and every version row. - Version history with publication time, deprecation, provenance, integrity hashes and unpacked size. - Download totals, daily rows and per-version counts, plus a 128-name batch. - Security advisories with severity, CWE ids and CVSS, and provenance attestations decoded from their bundles. - Search, dependents, users, orgs and the registry's name and change feeds. ## npm endpoints | Endpoint | Request | Credits | Docs | | --- | --- | --- | --- | | Package | GET /v1/npm/package | 1 credit Failed requests are free | [docs](https://www.socialfetch.dev/docs/api/v1/npm/package/get) | | Package details | GET /v1/npm/package/details | 1 credit Failed requests are free | [docs](https://www.socialfetch.dev/docs/api/v1/npm/package/details/get) | | Versions | GET /v1/npm/package/versions | 1 credit Failed requests are free | [docs](https://www.socialfetch.dev/docs/api/v1/npm/package/versions/get) | | Version | GET /v1/npm/package/version | 1 credit Failed requests are free | [docs](https://www.socialfetch.dev/docs/api/v1/npm/package/version/get) | | Downloads | GET /v1/npm/package/downloads | 1 credit Failed requests are free | [docs](https://www.socialfetch.dev/docs/api/v1/npm/package/downloads/get) | | Downloads by version | GET /v1/npm/package/downloads/versions | 1 credit Failed requests are free | [docs](https://www.socialfetch.dev/docs/api/v1/npm/package/downloads/versions/get) | | Downloads by name | GET /v1/npm/packages/downloads | 1 credit per name Up to 128 names per request Max 128 credits A name that is not found is still charged Failed requests are free | [docs](https://www.socialfetch.dev/docs/api/v1/npm/packages/downloads/get) | | Advisories | GET /v1/npm/package/advisories | 1 credit Failed requests are free | [docs](https://www.socialfetch.dev/docs/api/v1/npm/package/advisories/get) | | Provenance | GET /v1/npm/package/provenance | 1 credit Failed requests are free | [docs](https://www.socialfetch.dev/docs/api/v1/npm/package/provenance/get) | | Dependents | GET /v1/npm/package/dependents | 1 credit Failed requests are free | [docs](https://www.socialfetch.dev/docs/api/v1/npm/package/dependents/get) | | Search | GET /v1/npm/packages/search | 1 credit Failed requests are free | [docs](https://www.socialfetch.dev/docs/api/v1/npm/packages/search/get) | | User | GET /v1/npm/user | 1 credit Failed requests are free | [docs](https://www.socialfetch.dev/docs/api/v1/npm/user/get) | | User packages | GET /v1/npm/user/packages | 1 credit Failed requests are free | [docs](https://www.socialfetch.dev/docs/api/v1/npm/user/packages/get) | | Org | GET /v1/npm/org | 1 credit Failed requests are free | [docs](https://www.socialfetch.dev/docs/api/v1/npm/org/get) | | Org packages | GET /v1/npm/org/packages | 1 credit Failed requests are free | [docs](https://www.socialfetch.dev/docs/api/v1/npm/org/packages/get) | | Package names | GET /v1/npm/registry/packages | 1 credit Failed requests are free | [docs](https://www.socialfetch.dev/docs/api/v1/npm/registry/packages/get) | | Changes | GET /v1/npm/registry/changes | 1 credit Failed requests are free | [docs](https://www.socialfetch.dev/docs/api/v1/npm/registry/changes/get) | | Recent updates | GET /v1/npm/registry/recent | 1 credit Failed requests are free | [docs](https://www.socialfetch.dev/docs/api/v1/npm/registry/recent/get) | ## How to start 1. **Create an API key.** Sign up at Social Fetch and copy a key (`sfk_…`). New accounts get 100 free credits, enough to try a package, its versions and its downloads. 2. **Pick the route.** Use `GET /v1/npm/package?name=express` for the latest version and dist-tags, or `GET /v1/npm/package/downloads?name=express&period=last-week` for downloads. Send `x-api-key` on every request. 3. **Page and branch.** Check `data.lookupStatus` before storing a row. Keep calling with `page.nextCursor` while `page.hasMore` is true. Bill from `meta.creditsCharged`, and read `data.complete` and `data.missing` when a package answer was partial. ## Pricing Most npm routes charge one credit per completed request, and the downloads batch charges one credit per requested name, up to 128 names and 128 credits per request. Each page of a list is its own request. A request that fails with `503 temporarily_unavailable` is not charged. Credits never expire on pay-as-you-go packs, and `meta.creditsCharged` on every response is the billing source of truth. ## Compared with the official API npm publishes its registry and download data in several shapes for the same facts: package documents are large, version data is nested under a version key, download responses switch shape between total and daily, and a missing package comes back as an HTTP error. Social Fetch gives you one envelope and one paging model across all eighteen routes: typed `not_found`, decoded provenance attestations, advisories joined to the package, and the extra package facts (dependents count, weekly downloads) attached to the same package object. ## FAQ ### Is there an npm API for package metadata and downloads? Yes. Social Fetch has eighteen npm routes under /v1/npm for packages, full package documents, versions, single versions, downloads, per-version downloads, downloads for several names, advisories, provenance, dependents, search, users, orgs, package names, changes and recent updates. Authenticate with your Social Fetch API key in x-api-key. ### How do I name a package? Use the name as npm stores it: express, lodash.merge or @types/node. Scoped names need exactly one slash. Names are case-sensitive, so Express is a different package from express. A package that does not exist returns HTTP 200 with data.lookupStatus set to not_found. ### What is the difference between the package and package details routes? GET /v1/npm/package is the small answer: data.package for the latest version, data.distTags, data.latestVersion, data.downloads for last week and data.complete with data.missing when part of the answer could not be filled. GET /v1/npm/package/details returns the full registry document in data.package, including timestamps, stars, README, every version row, the dependents count and weekly downloads. ### How do downloads work? GET /v1/npm/package/downloads with period=last-day, last-week, last-month or last-year returns a total; add granularity=daily for one row per day in data.days. Give from and to instead of period for an explicit range. A range spans up to 18 months; a longer range keeps its newest 18 months and sets data.clamped. Download data starts on 2015-01-10. Omit name for the whole registry total. The newest day usually reads 0 because npm has not counted it yet, and some packages have gaps in their daily counts, so a month or year total can be lower than the sum of the daily rows. ### Can I fetch several packages in one request? GET /v1/npm/packages/downloads takes up to 128 comma-separated names and returns one row per name in data.results, in request order, with data.summary counting found, notFound and unavailable names. It charges one credit per requested name, including a name that is not found, up to 128 credits per request, and each result carries its own status. ### What does the provenance route return? GET /v1/npm/package/provenance returns data.attestations for one version, with kind, predicateType, subject, source repository and workflow, builder, runUrl and transparency log index. Signatures are decoded, not verified. A version that does not exist returns data.lookupStatus not_found; an existing version with no attestation is found with an empty attestations list. Add include=raw to also get each sigstore bundle in attestations[].raw. ### How far can I page through search and dependents? Search accepts 1 to 250 results per page and honours a starting offset only up to 5,000, so the deepest result is about 5,250. Dependents are 36 per page for at most 11 pages, so at most 396 names. Both use page.nextCursor and page.hasMore, and a page past the end is an empty page with hasMore false. ### Does HTTP 200 mean the package or user exists? No. HTTP 200 means the request finished. Check data.lookupStatus: not_found means the package, version, user or org does not exist. Lists such as dependents, search and package names are found with an empty array when nothing matched. ### What happens with a very large package document? GET /v1/npm/package/details caps the decoded document at 32 MB, which covers the largest packages in the registry (next is about 30 MB decoded). A package whose document is larger is refused instead of returning a partial answer. The smaller package route is the better choice for a quick latest-version lookup. ### Can I use the npm routes from agents or MCP? Yes. Every npm route is reachable through Ask (POST /v1/ask) in plain English and through MCP with the same credit metering as REST. Use the typed routes for production jobs and the agent surfaces for exploration. ## Related - [npm Package API](https://www.socialfetch.dev/platforms/npm/package): Latest version, dist-tags and last week's downloads (`GET /v1/npm/package`). - [npm Versions API](https://www.socialfetch.dev/platforms/npm/package-versions): Every version newest first, with deprecation and provenance (`GET /v1/npm/package/versions`). - [npm Downloads API](https://www.socialfetch.dev/platforms/npm/package-downloads): Totals and daily rows by period or day range (`GET /v1/npm/package/downloads`). - [npm Advisories API](https://www.socialfetch.dev/platforms/npm/package-advisories): Security advisories for a version or every version (`GET /v1/npm/package/advisories`). - [npm Search API](https://www.socialfetch.dev/platforms/npm/packages-search): Search by words and qualifiers, ranked by npm's score (`GET /v1/npm/packages/search`). - [Ask in plain English](https://www.socialfetch.dev/ask): Route a natural-language package question to the matching npm operation.