> **For coding agents and LLMs:** This is one page from the Social Fetch docs (markdown export). For curated orientation and workflow guidance, start with [`/llms.txt`](https://www.socialfetch.dev/llms.txt); for agent onboarding and crawl rules, use [`/agents.txt`](https://www.socialfetch.dev/agents.txt); for the full endpoint list with links to pages like this one, use [`/llms-endpoints.txt`](https://www.socialfetch.dev/llms-endpoints.txt); for one platform's parameters and curls, use [`/llms-{platform}.txt`](https://www.socialfetch.dev/llms-tiktok.txt); use [`/llms.json`](https://www.socialfetch.dev/llms.json) when you need structured JSON for tool registration.

## This page

- **On-site (HTML):** <https://www.socialfetch.dev/docs/api/v1/npm/package/downloads/versions/get>
- **Markdown (.mdx) URL:** <https://www.socialfetch.dev/docs/api/v1/npm/package/downloads/versions/get.mdx>

## API base URL and authentication

- **API origin (from OpenAPI `servers`):** `https://api.socialfetch.dev`
- **Authentication:** send `x-api-key: sfk_...` on `/v1/**` and `/v2/**` routes unless the operation is explicitly anonymous (check OpenAPI `security`, the [API reference hub](https://www.socialfetch.dev/docs/api.mdx), [`/llms.txt`](https://www.socialfetch.dev/llms.txt), or [`/llms.json`](https://www.socialfetch.dev/llms.json) for each route).
- **OpenAPI JSON:** <https://www.socialfetch.dev/openapi.json>

## Recommended docs entrypoints (this site)

- [Documentation overview](https://www.socialfetch.dev/docs.mdx) — top-level orientation (markdown).
- [Quickstart](https://www.socialfetch.dev/docs/quickstart.mdx) — authenticate with `x-api-key`, validate auth with `whoami`, and understand the JSON envelope.
- [SDK](https://www.socialfetch.dev/docs/sdk.mdx) — official TypeScript SDK guide, including `SocialFetchClient`, `Result`, and `unwrap()`.
- [Capability matrix](https://www.socialfetch.dev/docs/capability-matrix.mdx) — every operation with identifiers, pagination, outcomes, media download, credits, and its SDK method. Generated from OpenAPI, so use it for route selection instead of scanning individual pages.
- [Recipes](https://www.socialfetch.dev/docs/recipes.mdx) — copyable workflows (brand monitoring, transcripts, Ad Library, creator scoring, Reddit research) with credit callouts and SDK examples.
- [Integrations](https://www.socialfetch.dev/docs/integrations.mdx) — MCP for AI clients, n8n verified node, Apify Store Actors, Make custom app, SDK, and REST API connection paths.
- [MCP product page](https://www.socialfetch.dev/mcp) — hosted MCP overview, OAuth, Skills install.
- [MCP integration](https://www.socialfetch.dev/docs/integrations/mcp.mdx) — hosted `/mcp` server, OAuth, Cursor/VS Code/Claude install snippets, 910 endpoint tools, plus docs_search/docs_read for implementation help.
- [n8n integration](https://www.socialfetch.dev/docs/integrations/n8n.mdx) — install `n8n-nodes-socialfetch`, credentials, and workflow examples.
- [Apify integration](https://www.socialfetch.dev/docs/integrations/apify.mdx) — Store Actors under @social-fetch, PPE billing, dataset export, and quick start.
- [Make integration](https://www.socialfetch.dev/docs/integrations/make.mdx) — custom app modules for Make scenarios, API key credentials, and module catalog.
- [`/llms-endpoints.txt`](https://www.socialfetch.dev/llms-endpoints.txt) — every documented operation with a direct link to that route's agent-readable markdown page (prefer this over parsing OpenAPI).
- [`/llms-{platform}.txt`](https://www.socialfetch.dev/llms-tiktok.txt) — per-platform endpoint files generated from OpenAPI (parameters, credits, curls).
- [`/agents.txt`](https://www.socialfetch.dev/agents.txt) — agent crawl/onboarding file with capabilities, auth rules, and allowlist.
- [`/llms.json`](https://www.socialfetch.dev/llms.json) — structured machine-readable operation inventory with parameter names, pagination, outcomes, credits, and SDK mapping.
- [API reference hub](https://www.socialfetch.dev/docs/api.mdx) — human-friendly index of operations with links into generated pages.
- [Errors](https://www.socialfetch.dev/docs/errors.mdx) — shared error envelope and HTTP status guidance.
- [Credits](https://www.socialfetch.dev/docs/credits.mdx) — metering, `402`, and planning batch jobs.
- Outcome semantics such as `found`, `not_found`, and `private` are documented in [Errors](https://www.socialfetch.dev/docs/errors.mdx) and on operation pages when present in the OpenAPI contract.

## Markdown docs convention

- Every docs page has a markdown twin: append **`.mdx`** to the docs pathname (for example `/docs/quickstart` → `/docs/quickstart.mdx`).
- Agents that send `Accept: text/markdown` on `/docs/**` HTML URLs may receive markdown directly (same URL, `Vary: Accept`).
- Published blog posts use the same convention: `/blog/{slug}` → `/blog/{slug}.mdx`, or `Accept: text/markdown` on the HTML URL (`Vary: Accept`).

---
# Get npm downloads for every version (https://www.socialfetch.dev/docs/api/v1/npm/package/downloads/versions/get)

## Summary

Get last week's npm downloads for every version of a package.

**Tags:** `npm`

## HTTP

- **Method:** GET
- **Path:** `/v1/npm/package/downloads/versions`
- **operationId:** `npm.package.version_downloads.get`
- **Base URL:** `https://api.socialfetch.dev`

## Capability summary

- **SDK mapping:** `client.npm.getVersionDownloads({ name: "express" })`
- **Pagination:** none
- **Business outcome field:** `data.lookupStatus` with values `found`, `not_found`

## Credits

- **Base:** 1 credit per successful lookup.
- **Maximum on success (200):** 1 credit.
- **Failed requests (`lookup_failed`, `503`):** not charged.
- **Authoritative field:** `meta.creditsCharged`.

## Authentication

- **`x-api-key`**: API key (`sfk_...`)

## Parameters

### `name` (query)

- **Required:** yes
- **Constraints:** type `string`; maxLength: 214
- **Description:** npm package name, e.g. `express`, `lodash.merge`, `@types/node` or `--file--1`. Names are case-sensitive (`Express` is a different package) and keep legacy punctuation such as a leading `-`.

## Responses (status codes)

- **200**: npm downloads by version.
- **400**: Invalid request
- **401**: Missing or invalid API key
- **402**: Insufficient credits
- **413**: The document is larger than the maximum size we can return; no charge.
- **500**: Unexpected or billing error
- **502**: Lookup could not be completed.
- **503**: Service temporarily unavailable; safe to retry with backoff.

## Response body (200)

npm downloads by version.

### Field outline

- **data** (required) — type `object`. Endpoint-specific response payload.
  - **lookupStatus** (required) — type `string`; enum: found, not_found. Whether the item exists. Every outcome is HTTP 200; branch on this field.
  - **package** (required) — type `string`. Package name.
  - **downloads** (required) — type `object`. Weekly downloads keyed by version. Only keys that are a real version or dist-tag are kept; an unknown package is `not_found`.
  - **versionCount** (required) — type `integer`; minimum: 0. How many valid version keys the map has.
- **meta** (required) — type `object`. Metadata describing the request and billing outcome.
  - **requestId** (required) — type `string`; minLength: 1. Unique request identifier for tracing this API call.
  - **creditsCharged** (required) — type `integer`; minimum: 0. Credits charged for this request.
  - **version** (required) — type `string`; enum: v1. Public API version that served the response.

### Example JSON (found)

```json
{
  "data": {
    "lookupStatus": "found",
    "package": "express",
    "downloads": {
      "0.14.0": 916,
      "0.14.1": 3442,
      "1.0.0": 2424,
      "1.0.0beta": 22,
      "1.0.0beta2": 23,
      "1.0.0rc": 24,
      "1.0.0rc2": 32,
      "1.0.0rc3": 24,
      "1.0.0rc4": 25,
      "1.0.1": 121,
      "1.0.2": 83,
      "1.0.3": 80,
      "1.0.4": 105,
      "1.0.5": 95,
      "1.0.6": 81,
      "1.0.7": 127,
      "1.0.8": 229,
      "2.0.0": 940,
      "2.0.0beta": 26,
      "2.0.0beta2": 21,
      "2.0.0beta3": 25,
      "2.0.0rc": 25,
      "2.0.0rc2": 24,
      "2.0.0rc3": 24,
      "2.1.0": 67,
      "2.1.1": 359,
      "2.2.0": 70,
      "2.2.1": 66,
      "2.2.2": 84,
      "2.3.0": 71,
      "2.3.1": 71,
      "2.3.10": 121,
      "2.3.11": 83,
      "2.3.12": 244,
      "2.3.2": 78,
      "2.3.3": 113,
      "2.3.4": 75,
      "2.3.5": 66,
      "2.3.6": 77,
      "2.3.7": 73,
      "2.3.8": 68,
      "2.3.9": 62,
      "2.4.0": 76,
      "2.4.1": 62,
      "2.4.2": 70,
      "2.4.3": 88,
      "2.4.4": 70,
      "2.4.5": 71,
      "2.4.6": 86,
      "2.4.7": 80,
      "2.5.0": 547,
      "2.5.1": 104,
      "2.5.10": 458,
      "2.5.11": 45360,
      "2.5.2": 228,
      "2.5.3": 73,
      "2.5.4": 392,
      "2.5.5": 70,
      "2.5.6": 103,
      "2.5.7": 105,
      "2.5.8": 434,
      "2.5.9": 1495,
      "3.0.0": 5119,
      "3.0.0alpha1": 36,
      "3.0.0alpha2": 22,
      "3.0.0alpha3": 20,
      "3.0.0alpha4": 28,
      "3.0.0alpha5": 21,
      "3.0.0beta1": 36,
      "3.0.0beta2": 24,
      "3.0.0beta3": 28,
      "3.0.0beta4": 62,
      "3.0.0beta6": 24,
      "3.0.0beta7": 26,
      "3.0.0rc1": 24,
      "3.0.0rc2": 29,
      "3.0.0rc3": 33,
      "3.0.0rc4": 91,
      "3.0.0rc5": 95,
      "3.0.1": 915,
      "3.0.2": 83,
      "3.0.3": 386,
      "3.0.4": 106,
      "3.0.5": 137,
      "3.0.6": 5277,
      "3.1.0": 660,
      "3.1.1": 77,
      "3.1.2": 8700,
      "3.10.0": 60,
      "3.10.1": 63,
      "3.10.2": 70,
      "3.10.3": 66,
      "3.10.4": 62,
      "3.10.5": 129,
      "3.11.0": 127,
      "3.12.0": 74,
      "3.12.1": 65,
      "3.13.0": 71,
      "3.14.0": 172,
      "3.15.0": 131,
      "3.15.1": 74,
      "3.15.2": 95,
      "3.15.3": 68,
      "3.16.0": 191,
      "3.16.1": 176,
      "3.16.10": 257,
      "3.16.2": 65,
      "3.16.3": 63,
      "3.16.4": 71,
      "3.16.5": 58,
      "3.16.6": 70,
      "3.16.7": 68,
      "3.16.8": 70,
      "3.16.9": 175,
      "3.17.0": 136,
      "3.17.1": 193,
      "3.17.2": 148,
      "3.17.3": 68,
      "3.17.4": 606,
      "3.17.5": 110,
      "3.17.6": 76,
      "3.17.7": 66,
      "3.17.8": 126,
      "3.18.0": 64,
      "3.18.1": 101,
      "3.18.2": 72,
      "3.18.3": 236,
      "3.18.4": 68,
      "3.18.5": 96,
      "3.18.6": 91,
      "3.19.0": 68,
      "3.19.1": 141,
      "3.19.2": 76,
      "3.2.0": 270,
      "3.2.1": 77,
      "3.2.2": 78,
      "3.2.3": 69,
      "3.2.4": 486,
      "3.2.5": 5409,
      "3.2.6": 1811,
      "3.20.0": 75,
      "3.20.1": 65,
      "3.20.2": 123,
      "3.20.3": 118,
      "3.21.0": 160,
      "3.21.1": 70,
      "3.21.2": 38693,
      "3.3.0": 74,
      "3.3.1": 165,
      "3.3.2": 65,
      "3.3.3": 80,
      "3.3.4": 527,
      "3.3.5": 182,
      "3.3.6": 81,
      "3.3.7": 218,
      "3.3.8": 2930,
      "3.4.0": 1311,
      "3.4.1": 86,
      "3.4.2": 82,
      "3.4.3": 467,
      "3.4.4": 961,
      "3.4.5": 144,
      "3.4.6": 303,
      "3.4.7": 417,
      "3.4.8": 20949,
      "3.5.0": 152,
      "3.5.1": 894,
      "3.5.2": 102,
      "3.5.3": 1764,
      "3.6.0": 126,
      "3.7.0": 63,
      "3.8.0": 65,
      "3.8.1": 134,
      "3.9.0": 80,
      "4.0.0": 39375,
      "4.0.0-rc1": 92,
      "4.0.0-rc2": 61,
      "4.0.0-rc3": 59,
      "4.0.0-rc4": 64,
      "4.1.0": 1375,
      "4.1.1": 291,
      "4.1.2": 250,
      "4.10.0": 130,
      "4.10.1": 1190,
      "4.10.2": 327,
      "4.10.3": 97,
      "4.10.4": 292,
      "4.10.5": 125,
      "4.10.6": 1993,
      "4.10.7": 585,
      "4.10.8": 1621,
      "4.11.0": 778,
      "4.11.1": 278,
      "4.11.2": 1513,
      "4.12.0": 316,
      "4.12.1": 139,
      "4.12.2": 1138,
      "4.12.3": 1065,
      "4.12.4": 8862,
      "4.13.0": 1169,
      "4.13.1": 539,
      "4.13.2": 177,
      "4.13.3": 6764,
      "4.13.4": 25283,
      "4.14.0": 31523,
      "4.14.1": 14963,
      "4.15.0": 1682,
      "4.15.1": 369,
      "4.15.2": 20505,
      "4.15.3": 23023,
      "4.15.4": 16682,
      "4.15.5": 11275,
      "4.16.0": 11478,
      "4.16.1": 4401,
      "4.16.2": 182736,
      "4.16.3": 189910,
      "4.16.4": 526306,
      "4.17.0": 44432,
      "4.17.1": 3046554,
      "4.17.2": 222983,
      "4.17.3": 792113,
      "4.18.0": 31836,
      "4.18.1": 1278203,
      "4.18.2": 4995064,
      "4.18.3": 212895,
      "4.19.0": 4434,
      "4.19.1": 24841,
      "4.19.2": 2895549,
      "4.2.0": 42426,
      "4.20.0": 555874,
      "4.21.0": 826723,
      "4.21.1": 1532685,
      "4.21.2": 17376765,
      "4.22.0": 945909,
      "4.22.1": 13897266,
      "4.22.2": 17463767,
      "4.22.3": 23789459,
      "4.3.0": 21649,
      "4.3.1": 92,
      "4.3.2": 366,
      "4.4.0": 394,
      "4.4.1": 120,
      "4.4.2": 87,
      "4.4.3": 88,
      "4.4.4": 252,
      "4.4.5": 663,
      "4.5.0": 395,
      "4.5.1": 515,
      "4.6.0": 90,
      "4.6.1": 13417,
      "4.7.0": 83,
      "4.7.1": 90,
      "4.7.2": 95,
      "4.7.3": 278,
      "4.7.4": 222,
      "4.8.0": 115,
      "4.8.1": 155,
      "4.8.2": 121,
      "4.8.3": 121,
      "4.8.4": 96,
      "4.8.5": 255,
      "4.8.6": 103,
      "4.8.7": 358,
      "4.8.8": 498,
      "4.9.0": 302,
      "4.9.1": 108,
      "4.9.2": 98,
      "4.9.3": 130,
      "4.9.4": 432,
      "4.9.5": 200,
      "4.9.6": 145,
      "4.9.7": 136,
      "4.9.8": 4123,
      "5.0.0": 94533,
      "5.0.0-alpha.1": 206,
      "5.0.0-alpha.2": 227,
      "5.0.0-alpha.3": 110,
      "5.0.0-alpha.4": 51,
      "5.0.0-alpha.5": 644,
      "5.0.0-alpha.6": 169,
      "5.0.0-alpha.7": 943,
      "5.0.0-alpha.8": 9077,
      "5.0.0-beta.1": 6286,
      "5.0.0-beta.2": 192,
      "5.0.0-beta.3": 5436,
      "5.0.1": 495306,
      "5.1.0": 14242191,
      "5.2.0": 74431,
      "5.2.1": 71367779,
      "5.3.0": 35700545
    },
    "versionCount": 290
  },
  "meta": {
    "requestId": "req_c7801900-71a5-4ee7-bf05-fa711c47b7d3",
    "creditsCharged": 1,
    "version": "v1"
  }
}
```

### Machine-readable error codes

When an error JSON body is returned, it may include one of these `error.code` values (derived from the OpenAPI schemas for this operation; additional codes may exist at runtime):

- `bad_request`

## Error handling & retries

Interpret HTTP status codes using the descriptions below. Do not assume a JSON body unless the OpenAPI schema defines one for that status.

- **400**: Invalid request **Retry:** Fix the request; retrying the same invalid payload will not help.
- **401**: Missing or invalid API key **Retry:** Fix the API key first; retrying without changes will not help.
- **402**: Insufficient credits **Retry:** Do not retry without resolving billing/credits (retrying the same request will not help).
- **413**: The document is larger than the maximum size we can return; no charge.
- **500**: Unexpected or billing error
- **502**: Lookup could not be completed. **Retry:** May be transient; a few retries with backoff are reasonable.
- **503**: Service temporarily unavailable; safe to retry with backoff. **Retry:** Usually safe to retry with exponential backoff and jitter.

### Suggested client defaults

- Send the API key using the `x-api-key` header on every request.
- On `503` (and sometimes `502`), retry with backoff; cap retries and surface a clear error to the user.
- On `402`, surface an actionable billing message rather than blind retries.

## Examples

### TypeScript SDK

```typescript
import { SocialFetchClient } from "@socialfetch/sdk";

const client = new SocialFetchClient({
  apiKey: process.env.SOCIALFETCH_API_KEY!,
});

const result = await client.npm.getVersionDownloads({
  name: "express",
});

if (!result.ok) {
  console.error(result.error);
} else {
  console.log(result.value.data);
}
```

### Node.js

```javascript
const response = await fetch(
  "https://api.socialfetch.dev/v1/npm/package/downloads/versions?name=express",
  {
    headers: {
      "x-api-key": "YOUR_API_KEY"
    }
  }
);

const data = await response.json();
console.log(data);
```

### cURL

```bash
curl "https://api.socialfetch.dev/v1/npm/package/downloads/versions?name=express" \
  -H "x-api-key: YOUR_API_KEY"
```

### Python

```python
import requests

response = requests.get(
    "https://api.socialfetch.dev/v1/npm/package/downloads/versions?name=express",
    headers={"x-api-key": "YOUR_API_KEY"},
)
data = response.json()
print(data)
```