pyamplitude is a modern, offline-testable Python client for Amplitude Analytics APIs.
This rewrite targets the current Amplitude API families instead of the legacy 2017 Dashboard-only surface:
- Dashboard REST API
- Export API
- Behavioral Cohorts API, including asynchronous cohort export requests
- HTTP V2 ingestion API
- Batch Event Upload API
- Optional Redshift helpers for historical Amplitude exports
The package is designed to be tested without real Amplitude credentials. Every client accepts an injectable transport, so unit tests can validate URLs, auth, query parameters, JSON payloads, response parsing and error handling locally.
pip install pyamplitudeFor local development:
python -m pip install -e ".[dev]"
python -m pytestFor optional Redshift support:
python -m pip install "pyamplitude[redshift]"Dashboard, Export and Behavioral Cohorts use Basic Auth with an API key and secret key:
from pyamplitude import AmplitudeCredentials
credentials = AmplitudeCredentials(
api_key="AMPLITUDE_API_KEY",
secret_key="AMPLITUDE_SECRET_KEY",
project_name="production",
)HTTP V2 and Batch ingestion only require the API key:
from pyamplitude.ingestion import make_ingestion_credentials
credentials = make_ingestion_credentials("AMPLITUDE_API_KEY")US and EU regions are supported:
from pyamplitude import BatchClient
client = BatchClient(credentials, region="EU")from pyamplitude import AmplitudeEvent, HTTPV2Client
from pyamplitude.ingestion import make_ingestion_credentials
client = HTTPV2Client(make_ingestion_credentials("AMPLITUDE_API_KEY"))
client.upload([
AmplitudeEvent(
event_type="Signup",
user_id="user-123",
event_properties={"source": "docs"},
insert_id="signup-user-123",
)
])from pyamplitude import AmplitudeCredentials, DashboardClient, Segment
credentials = AmplitudeCredentials(api_key="key", secret_key="secret")
client = DashboardClient(credentials)
segment = Segment.user_property("country", "is", ["Uruguay"])
data = client.active_users(
start="20240101",
end="20240131",
mode="active",
interval=1,
segments=[segment],
group_by="country",
)from pyamplitude import AmplitudeCredentials, ExportClient
client = ExportClient(AmplitudeCredentials(api_key="key", secret_key="secret"))
events = client.export_events(start="20240101T00", end="20240101T23")from pyamplitude import AmplitudeCredentials, CohortsClient
client = CohortsClient(AmplitudeCredentials(api_key="key", secret_key="secret"))
job = client.request_cohort("cohort-id", include_properties=True)
status = client.request_status(job["request_id"])
archive = client.download_cohort(job["request_id"])The old import paths still exist as wrappers:
from pyamplitude.amplituderestapi import AmplitudeRestApi
from pyamplitude.behavioralcohortsapi import BehavioralCohortsApi
from pyamplitude.exportapi import AmplitudeExportApi
from pyamplitude.projectshandler import ProjectsHandlerNew code should prefer DashboardClient, CohortsClient, ExportClient,
HTTPV2Client and BatchClient.
The project does not require real Amplitude credentials for normal test runs.
python -m pytestIntegration tests should be marked with @pytest.mark.integration and skipped unless
these environment variables exist:
AMPLITUDE_API_KEYAMPLITUDE_SECRET_KEYAMPLITUDE_PROJECT_ID
Sphinx documentation lives in docs/source.
python -m sphinx -b html docs/source docs/_build/htmlProject status badges in this README and the Sphinx documentation track the
develop branch until a release branch is promoted.
Release builds use semantic version tags such as v2.0.0. The PyPI long
description is sourced from this README through pyproject.toml.
Current Amplitude API references: