DevPyPI download statistics · PyPI Stats

pypi.downloads

Uses PyPI Stats, a separate service from PyPI. kind recent returns last-day/week/month totals; overall returns daily history excluding known mirrors, retained for up to 180 days. Data updates daily and is cached for 24 hours per API process with shared in-flight requests. Rate-limit cooldowns apply; fetched_at reports retrieval time, not the upstream data timestamp. No provider key needed.

POST/v1/capabilities/pypi.downloads/execute

Charge returned per callStable

operationId: executePypiDownloads
Source: PyPI Stats
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 PyPI Stats API with a 24-hour process-local cache. 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/pypi.downloads/execute, JSON, validated against the PypiDownloadsRequest component of the public OpenAPI document. Defaults are applied server-side, so an omitted optional field behaves exactly as its default.

Request fields of pypi.downloads
Field	Description
packagestringREQUIRED	PyPI project name. Case and runs of hyphens, underscores and dots are normalized.min length 1 · max length 214 · pattern ^[A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?$
kind"recent" \| "overall"	recent: last day/week/month totals. overall: daily history (up to 180 days), excluding known mirrors. Source: PyPI Stats, not the PyPI metadata API.Default `"recent"`.

Unknown keys are rejected with 400 invalid_request.

Examples

Recent totals

curl

curl -s -X POST https://api.powerups-ai.store/v1/capabilities/pypi.downloads/execute \
  -H "Authorization: Bearer $AIPA_API_KEY" -H "Content-Type: application/json" \
  -d '{"package":"requests","kind":"recent"}'

Daily history without mirrors

curl

curl -s -X POST https://api.powerups-ai.store/v1/capabilities/pypi.downloads/execute \
  -H "Authorization: Bearer $AIPA_API_KEY" -H "Content-Type: application/json" \
  -d '{"package":"requests","kind":"overall"}'

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 PypiDownloadsRecord 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 pypi.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"recent" \| "overall"ALWAYS	On every record.
sourcestringALWAYS	On every record.
dataobject \| object[]ALWAYS	On every record.
fetched_atstringALWAYS	On every record.
cache_hitbooleanALWAYS	On every record.
mirrorsbooleanALWAYS	On every record.

Caveats

PyPI Stats is a separate provider. Data updates daily; daily history covers up to 180 days. Known mirrors are excluded.
Results are cached for 24 hours per API process; restarts clear the cache and replicas have separate caches. 256 package/endpoint entries maximum; fresh entries are not evicted. Requests for new entries fail when full.
An upstream 429 pauses new cache misses for Retry-After, or one hour when absent; existing cached results remain available. fetched_at is retrieval time, not a claim about the latest data date.

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/pypi.downloads/execute", {
  body: {
    "package": "requests",
    "kind": "recent"
  },
});
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/pypi.downloads/execute

{
  "package": "requests",
  "kind": "recent"
}