Devnpm download statistics · npm Downloads API

npm.downloads

Retrieve download totals (kind: point) or daily counts (kind: range) for one public npm package. Supports last-day, last-week, last-month, last-year, a date, or an inclusive date range. last-month means the last 30 available days, not the previous calendar month. Returns the actual start and end dates from npm; upstream limits a request to 18 months.

POST/v1/capabilities/npm.downloads/execute

Charge returned per callStable

operationId: executeNpmDownloads
Source: npm Downloads API
Typical credits: 0 (free source)
Search deadline: 15 s server-side
Paging: single result
Availability: ConfiguredChecked 2026-11-03 16:34 UTC

Cost basis

Free public npm API; no provider API key required. Availability is reported per deployment by GET /v1/catalog (available). The timestamped snapshot describes configuration, not provider uptime or your account's enabled choices. Check the catalog with your own key before a call. Credits are explained under credits and limits.

Request body

Body of POST /v1/capabilities/npm.downloads/execute, JSON, validated against the NpmDownloadsRequest component of the public OpenAPI document. Defaults are applied server-side, so an omitted optional field behaves exactly as its default.

Request fields of npm.downloads
Field	Description
packagestringREQUIRED	Public npm package name, including scoped names such as @babel/core.min length 1 · max length 214 · pattern ^(?:@[a-zA-Z0-9_~][a-zA-Z0-9._~-]/)?[a-zA-Z0-9_~][a-zA-Z0-9._~-]$
periodstring	Named period, YYYY-MM-DD, or inclusive YYYY-MM-DD:YYYY-MM-DD range (upstream limit: 18 months). last-month is the last 30 available days, not the previous calendar month.Default `"last-month"`.pattern ^(last-day\|last-week\|last-month\|last-year\|[0-9]{4}-[0-9]{2}-[0-9]{2}(:[0-9]{4}-[0-9]{2}-[0-9]{2})?)$
kind"point" \| "range"	point returns a total; range returns daily counts.Default `"point"`.

Unknown keys are rejected with 400 invalid_request.

Rules the schema cannot express

Checked after schema validation; violations return 400 invalid_request with a plain message.

Explicit dates must be valid calendar dates; the end date must not precede the start date.

Examples

Last 30 available days

curl

curl -s -X POST https://api.powerups-ai.store/v1/capabilities/npm.downloads/execute \
  -H "Authorization: Bearer $AIPA_API_KEY" -H "Content-Type: application/json" \
  -d '{"package":"zod","period":"last-month","kind":"point"}'

Daily counts

curl

curl -s -X POST https://api.powerups-ai.store/v1/capabilities/npm.downloads/execute \
  -H "Authorization: Bearer $AIPA_API_KEY" -H "Content-Type: application/json" \
  -d '{"package":"zod","period":"last-month","kind":"range"}'

Calendar month

curl

curl -s -X POST https://api.powerups-ai.store/v1/capabilities/npm.downloads/execute \
  -H "Authorization: Bearer $AIPA_API_KEY" -H "Content-Type: application/json" \
  -d '{"package":"zod","period":"2026-08-01:2026-08-31"}'

Record fields

Each item in results[] carries record_id and title (contract, always present) and usually url and snippet. The other keys below are the documented tier: produced deterministically by this capability, omitted when the source has no value, checked against recorded source fixtures in our test suite, and published as the NpmDownloadsRecord component (all optional, extra keys allowed) so generated clients type them. The wire schema itself still validates only the base keys. Anything else comes from the provider and may change; see stability tiers.

Record keys of npm.downloads
Key	Note
record_idstringALWAYS	Use it with record actions on `POST /v1/follow-up`.
titlestringALWAYS	Contract key.
urlstring	Contract key; usually present.
snippetstring	Contract key; usually present.
packagestringALWAYS	On every record.
kind"point" \| "range"ALWAYS	On every record.
startstringALWAYS	On every record.
endstringALWAYS	On every record.
downloadsinteger \| object[]ALWAYS	Total, or daily { day, downloads } entries for range.

Caveats

last-month means the last 30 available days. Use returned inclusive start/end dates. npm limits each request to 18 months.

Follow-ups

Paging: Single result; more is refused with 400 invalid_request.

Not offered: update and record actions.

Detail behaviour: No record actions.

Record detail objects of this capability are provider-shaped: documented by observation, not by schema. Full follow-up semantics: follow-up.

Typed client

With types generated from the public document (see types, client and samples) the call is path-keyed and the body is checked at compile time:

TypeScript (openapi-fetch)

const { data, error } = await client.POST("/v1/capabilities/npm.downloads/execute", {
  body: {
    "package": "zod",
    "period": "last-month",
    "kind": "point"
  },
});
if (error) throw new Error(`${error.error.code}: ${error.error.message}`);
for (const record of data.results) console.log(record.record_id, record.title);

Recorded responseproduction · 27 Sep

Request

POST /v1/capabilities/npm.downloads/execute

{
  "package": "zod",
  "period": "last-month",
  "kind": "point"
}