Installation

This SDK is the server half of your integration. Your users read and write feeds from your app with a client SDK, and anything that needs a connected user or a live WebSocket belongs there: the state layer, device push registration, and client-side error handling. See the client-side overview for what lives there. Token signing stays on this side, because it needs your API secret.

Stream CLI and Agent Skills

Manage Stream from your terminal with the Stream CLI, including scripting and AI-agent workflows. Install the CLI and the default Agent Skills:

curl -fsSL https://getstream.io/cli.sh | bash
getstream skills

Then ask your agent in plain English, for example:

/stream List feed groups in my app.

See the CLI docs and Agent Skills docs for more.

pip install getstream

GitHub repository: https://github.com/GetStream/stream-py. Feel free to submit bug reports and feature requests.

The package is tested against these environments:

Python 3.7+
Python 3.8+
Python 3.9+
Python 3.10+
Python 3.11+
Python 3.12+

To create a client, you'll need your API key and secret. Both of them can be found in your Stream Dashboard.

You can optionally configure request timeouts and the HTTP connection pool. The default request timeout is 30 seconds.

import stream

# Create client with default settings (30s request timeout)
client = stream.connect('api_key', 'api_secret')

# Or create client with a custom request timeout (in seconds)
client = stream.connect('api_key', 'api_secret', request_timeout=30.0)

# Get the feeds client
feeds_client = client.feeds

# Your feeds operations here...

Alternative initialization

You can also initialize the client using environment variables:

import os
import stream

# Set environment variables
os.environ['STREAM_API_KEY'] = 'your_api_key'
os.environ['STREAM_API_SECRET'] = 'your_api_secret'

# Initialize client from environment
client = stream.connect_from_env()

# Get the feeds client
feeds_client = client.feeds

Connection pool and timeouts

The shared defaults and tuning options are documented on Connection pooling; this section covers the Python specifics.

The SDK keeps a pooled, keep-alive HTTP client (httpx). Tune it with constructor arguments:

Argument	Default	Description
`request_timeout` (alias `timeout`)	`30.0`	Per-request timeout in seconds.
`max_conns_per_host`	`5`	Maximum concurrent connections per host.
`idle_timeout`	`55.0`	Idle connection lifetime in seconds.
`connect_timeout`	`10.0`	TCP + TLS handshake timeout in seconds.

client = stream.connect(
    'api_key', 'api_secret',
    request_timeout=30.0,
    max_conns_per_host=10,
    idle_timeout=55.0,
    connect_timeout=10.0,
)

Each knob can also be set via an environment variable: STREAM_REQUEST_TIMEOUT (or STREAM_TIMEOUT), STREAM_MAX_CONNS_PER_HOST, STREAM_IDLE_TIMEOUT, and STREAM_CONNECT_TIMEOUT.

To supply your own HTTP client, pass http_client (an httpx.Client) or a custom transport. When http_client is set, the pool arguments above are not applied.

Quick Start

Architecture & Benchmark