RTB House SDK
Overview
This library provides an easy-to-use Python interface to RTB House API. It allows you to read and manage your campaigns settings, browse offers, download statistics etc.
API docs: https://api.panel.rtbhouse.com/api/docs
Installation
RTB House SDK can be installed with pip:
$ pip install rtbhouse_sdk
Usage example
Let’s write a script which fetches campaign stats (imps, clicks, postclicks) and shows the result as a table (using tabulate library).
First set up virtualenv and install requirements:
$ pip install rtbhouse_sdk tabulate
Create an API token in the RTB House Clients Panel (https://panel.rtbhouse.com/user/api-tokens) and copy it to a safe place.
Now you can initialize the API token in local file storage. Paste your API token in prompt after running the command below:
$ python -m rtbhouse_sdk.api_tokens init-json Paste your token: PASTE_YOUR_TOKEN_HERE
The authentication token is now ready to use. As long as you use it with the client frequently enough, the SDK will keep the token valid and rotate it automatically (for details see API Token Authentication below):
from datetime import date, timedelta
from operator import attrgetter
from rtbhouse_sdk.api_tokens import ApiTokenManager, JsonFileApiTokenStorage
from rtbhouse_sdk.client import Client
from rtbhouse_sdk.schema import CountConvention, StatsGroupBy, StatsMetric
from tabulate import tabulate
if __name__ == "__main__":
storage = JsonFileApiTokenStorage()
auth = ApiTokenManager(storage)
with Client(auth=auth) as api:
advertisers = api.get_advertisers()
day_to = date.today()
day_from = day_to - timedelta(days=30)
group_by = [StatsGroupBy.DAY]
metrics = [
StatsMetric.IMPS_COUNT,
StatsMetric.CLICKS_COUNT,
StatsMetric.CAMPAIGN_COST,
StatsMetric.CONVERSIONS_COUNT,
StatsMetric.CTR
]
stats = api.get_rtb_stats(
advertisers[0].hash,
day_from,
day_to,
group_by,
metrics,
count_convention=CountConvention.ATTRIBUTED_POST_CLICK,
)
columns = group_by + metrics
data_frame = [
[getattr(row, c.name.lower()) for c in columns]
for row in reversed(sorted(stats, key=attrgetter("day")))
]
print(tabulate(data_frame, headers=columns))Authentication methods
The SDK supports several authentication methods.
API Token Authentication
API Tokens provide a secure and manageable way to grant programmatic access without using a login and password. This allows you to connect your integrations to the API, without specific user credentials.
API tokens have a limited lifetime and must be periodically rotated and actively used to prevent expiration. For more details on the API token lifecycle, see the LEARN MORE link in the Clients Panel API Tokens section.
For automatic token lifecycle management, use ApiTokenManager / AsyncApiTokenManager as authentication classes.
These classes support per-request token resolution and allow the token to be stored/retrieved with a storage backend. Currently, for production use, SDK provides a JSON file storage backend.
When used with a storage backend, the SDK can:
rotate the token automatically when it enters the rotation window and overwrite the stored token with the new one
keep the token valid without manual maintenance
Rotation eligibility is checked on every request, which means that for typical integrations with regular traffic, you can configure the token once and let the SDK manage it automatically.
For integrations that do not make requests frequently enough to trigger automatic rotation during the rotation window (e.g. at least once a day), use the keep-alive-json CLI command (see CLI for API Tokens below) scheduled with cron or a similar tool.
CLI for API Tokens
A CLI interface is available to manage API tokens from the command line:
$ python -m rtbhouse_sdk.api_tokens <command> [options]
init-json
Initialize JSON file storage with API Token.
First create your API token in the Clients Panel (https://panel.rtbhouse.com/user/api-tokens).
Then provide the token via stdin or interactively when prompted:
$ python -m rtbhouse_sdk.api_tokens init-json Paste your token: PASTE_YOUR_TOKEN_HERE $ python -m rtbhouse_sdk.api_tokens init-json <<< "$API_TOKEN" $ python -m rtbhouse_sdk.api_tokens init-json < token.txt $ python -m rtbhouse_sdk.api_tokens init-json --path /custom/path/to/token.json
keep-alive-json
Keep alive a token stored in JSON file storage.
This command refreshes the token’s last activity timestamp and optionally rotates the token, if it is in the rotation window.
While you can run this command manually whenever needed, it is recommended to schedule it to run periodically at least once a day, to ensure the token remains active and does not expire:
$ python -m rtbhouse_sdk.api_tokens keep-alive-json $ python -m rtbhouse_sdk.api_tokens keep-alive-json --skip-auto-rotate $ python -m rtbhouse_sdk.api_tokens keep-alive-json --path /custom/path/to/token.json
API Token Storage Backends
Storage backends are responsible for persisting API tokens.
Storage backends must be initialized before use. API token manager classes provide a configure(token) method to initialize the token programmatically. This method will fetch the token details and save them to storage.
JSON File Storage
Persist tokens on disk using a JSON file. Use sync JsonFileApiTokenStorage or async AsyncJsonFileApiTokenStorage classes.
Storage can be initialized by manager.configure(token) method call or by using the init-json CLI command.
Sync example:
from rtbhouse_sdk.api_tokens import ApiTokenManager, JsonFileApiTokenStorage
from rtbhouse_sdk.client import Client
storage = JsonFileApiTokenStorage()
auth = ApiTokenManager(storage)
with Client(auth=auth) as api:
info = api.get_user_info()Async example:
from rtbhouse_sdk.api_tokens import AsyncApiTokenManager, AsyncJsonFileApiTokenStorage
from rtbhouse_sdk.client import AsyncClient
storage = AsyncJsonFileApiTokenStorage()
auth = AsyncApiTokenManager(storage)
async with AsyncClient(auth=auth) as api:
info = await api.get_user_info()In-Memory Storage
For simple scenarios where true persistence is not required.
Use sync InMemoryApiTokenStorage or async AsyncInMemoryApiTokenStorage classes.
from rtbhouse_sdk.api_tokens import ApiTokenManager, InMemoryApiTokenStorage
from rtbhouse_sdk.client import Client
storage = InMemoryApiTokenStorage(None)
manager = ApiTokenManager(storage)
manager.configure("your_api_token") # fetches token details and saves to storage
with Client(auth=manager) as api:
info = api.get_user_info()Custom Storage Backend
You can implement your own storage backend by subclassing ApiTokenStorage (sync) or AsyncApiTokenStorage (async). Each backend must implement three methods:
acquire_exclusive_for_update() — a context manager ensuring exclusive access to the storage
load() — load and return the current ApiToken
save(api_token) — persist the given ApiToken
API Token Auth (without automatic rotation and storage management)
Use ApiTokenAuth if you want to authenticate with a fixed API token without automatic rotation or storage management.
from rtbhouse_sdk.client import ApiTokenAuth, Client
auth = ApiTokenAuth("your_api_token")
with Client(auth=auth) as api:
info = api.get_user_info()from rtbhouse_sdk.client import ApiTokenAuth, AsyncClient
auth = ApiTokenAuth("your_api_token")
async with AsyncClient(auth=auth) as api:
info = await api.get_user_info()Basic Auth
Username and password authentication using BasicAuth.
from rtbhouse_sdk.client import BasicAuth, Client
auth = BasicAuth(username="jdoe", password="abcd1234")
with Client(auth=auth) as api:
info = api.get_user_info()Basic Token Auth
Token-based authentication using BasicTokenAuth.
from rtbhouse_sdk.client import BasicTokenAuth, Client
auth = BasicTokenAuth("your_basic_token")
with Client(auth=auth) as api:
info = api.get_user_info()License
5 maintainers
Metadata
5 maintainers
Release files for rtbhouse-sdk 16.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| rtbhouse_sdk-16.1.0.tar.gz | 18.5 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| rtbhouse_sdk-16.1.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 38.3 kB
Release files / rtbhouse_sdk-16.1.0.tar.gz
| Download URL | rtbhouse_sdk-16.1.0.tar.gz |
|---|---|
| Size | 18.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
d78338428ac56a2e1be630117e02d810c04dbbda11cfb10ad05cccc6923cfa4b
|
|
BLAKE2b-256 checksum How to use checksums |
91a9e53bf49e1348411fd243b65f755c4369ddca50852f7799588f9d429e246a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 15, 2026.
Transparency logRelease files / rtbhouse_sdk-16.1.0-py3-none-any.whl
| Download URL | rtbhouse_sdk-16.1.0-py3-none-any.whl |
|---|---|
| Size | 19.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d00a93d054c5fb98e1ef327f0dbca2031a5f26e6aa07ff9d326ffcbe6a3cf9f6
|
|
BLAKE2b-256 checksum How to use checksums |
6c604fd015d2d4e37ac604d5f1604062d539b8126260440d1ce55c3df5c275d9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 15, 2026.
Transparency log
