Client Configuration

Stream's server-side SDKs ship with default HTTP settings designed for typical use. The shared pool and timeout knobs are documented on Connection pooling. For high-traffic applications or specific network environments, you may need to tune these settings.

Default Settings

Every server SDK defaults to a 30 second request timeout, a 10 second connect timeout, 100 connections per host, a 55 second idle timeout, and 3 retries. The connection pooling page is the source for those defaults and for the per-language constructors. The snippets below show how to override them.

Customizing Settings

Node

Node.js

import { Agent } from "undici";

const client = new StreamClient("YOUR_API_KEY", "YOUR_API_SECRET", {
  timeout: 10000, // Request timeout in milliseconds
  agent: new Agent({
    keepAliveTimeout: 30000, // Keep-alive timeout in ms
    keepAliveMaxTimeout: 60000, // Max keep-alive timeout in ms
    connections: 50, // Max concurrent connections per host
    pipelining: 1, // HTTP pipelining
  }),
});

Option	Type	Default	Description
`timeout`	number	30000	Request timeout in milliseconds. Default is 30 seconds.
`agent`	Agent	Default	Custom Undici agent for connection pooling and keep-alive tuning.

Python

client = Stream(
    api_key="YOUR_API_KEY",
    api_secret="YOUR_API_SECRET",
    timeout=10.0,  # Request timeout in seconds
)

Parameter	Type	Default	Description
`timeout`	float	30.0	Request timeout in seconds.

The Python SDK uses httpx.Client internally with a pool of 10 connections per host. For advanced pooling, extend the base client with a custom httpx.Client.

Go

// Create HTTP client with persistent connections and tuned settings
transport := &http.Transport{
    DialContext: (&net.Dialer{
        Timeout:   30 * time.Second,
        KeepAlive: 30 * time.Second,
    }).DialContext,
    MaxIdleConns:        100,
    MaxIdleConnsPerHost: 100,
    IdleConnTimeout:     90 * time.Second,
    TLSHandshakeTimeout: 10 * time.Second,
}

httpClient := &http.Client{
    Transport: transport,
    Timeout:   30 * time.Second,
}

client, err := getstream.NewClient("YOUR_API_KEY", "YOUR_API_SECRET",
    getstream.WithTimeout(30 * time.Second),
    getstream.WithHTTPClient(httpClient),
)
if err != nil {
    panic(err)
}

Option	Default	Description
`WithTimeout(duration)`	30s	Request timeout.
`WithHTTPClient(client)`	Default http.Client	Custom HTTP client with full transport control.
`WithLogger(logger)`	Default logger	Custom logger for debugging.

Transport settings:

Setting	Default	Recommended	Description
`DialContext.Timeout`	30s	30s	TCP connection establishment timeout.
`DialContext.KeepAlive`	30s	30s	TCP keep-alive probe interval.
`MaxIdleConns`	100	100-200	Max idle connections across all hosts.
`MaxIdleConnsPerHost`	2	50-100	Max idle connections per host. Increase for high throughput.
`IdleConnTimeout`	90s	90s	How long idle connections stay in the pool.
`TLSHandshakeTimeout`	10s	10s	TLS handshake timeout.

Java

// Via properties
Properties props = new Properties();
props.put("io.getstream.apiKey", "YOUR_API_KEY");
props.put("io.getstream.apiSecret", "YOUR_API_SECRET");
props.put("io.getstream.timeout", "15000");  // Request timeout in milliseconds

var client = new StreamSDKClient(props);

Property	Env Variable	Default	Description
`io.getstream.timeout`	`STREAM_API_TIMEOUT`	10000	Request timeout in milliseconds (OkHttp `callTimeout`).

The Java SDK uses OkHttp with a connection pool of 5 idle connections and 59-second idle timeout. For custom pooling, provide a configured StreamHTTPClient instance.

PHP

use GuzzleHttp\Client as GuzzleClient;

// Custom Guzzle client with tuned settings
$httpClient = new GuzzleClient([
    'timeout' => 15,           // Request timeout in seconds
    'connect_timeout' => 5,    // Connection timeout in seconds
]);

$client = (new ClientBuilder())->apiKey('YOUR_API_KEY')
    ->apiSecret('YOUR_API_SECRET')
    ->httpClient($httpClient)
    ->build();

Setting	Default	Description
`timeout`	30s	Request timeout in seconds.
`connect_timeout`	10s	TCP connection timeout in seconds.
Retry on 429	3 attempts	Automatic exponential backoff with jitter on rate limit responses.

Ruby

client = GetStreamRuby::Client.new(
  api_key: "YOUR_API_KEY",
  api_secret: "YOUR_API_SECRET",
  timeout: 15,  # Request timeout in seconds
)

Parameter	Default	Description
`timeout`	30s	Request timeout in seconds.
Retry	3 attempts	Exponential backoff (0.05s base, 2x factor, 0.5 randomness).

.NET

// The .NET SDK uses HttpClient with framework defaults.
// For production tuning, configure via IHttpClientFactory:
builder.Services.AddHttpClient("stream", client =>
{
    client.Timeout = TimeSpan.FromSeconds(15);
})
.ConfigurePrimaryHttpMessageHandler(() => new SocketsHttpHandler
{
    PooledConnectionLifetime = TimeSpan.FromMinutes(2),
    PooledConnectionIdleTimeout = TimeSpan.FromMinutes(1),
    MaxConnectionsPerServer = 50,
});

Setting	Default	Description
`Timeout`	30s	Request timeout.
`PooledConnectionLifetime`	Unlimited	How long a connection lives before being replaced.
`MaxConnectionsPerServer`	Unlimited	Max connections per server.

Recommendations for High-Traffic Applications

Increase MaxIdleConnsPerHost (Go) or equivalent — the default of 2 per host is too low for high-throughput moderation workloads.
Set explicit timeouts when a call should return faster than the 30 second default.
Enable connection reuse — all SDKs enable keep-alive by default. Avoid creating new client instances per request.
Monitor for connection exhaustion — if you see connection errors under load, increase pool sizes.
Use a single client instance — instantiate the Stream client once and reuse it across your application. All SDKs are thread-safe / goroutine-safe.