Discord Labs Python SDK

A user-friendly Python client for the Discord Labs API. This package makes it simple to fetch public data (bots, users, website stats) and post authenticated bot statistics.

Links

• Conscherry
• Discord Labs
• Labs API Documentation
• Labs API Source
• JavaScript SDK on npm
• Python SDK on PyPI

Installation

python -m pip install labs-api-python

Quick start

Synchronous Client

from labs import LabsApiClient

with LabsApiClient() as client:
    bots = client.list_bots(limit=5)
    print(bots)

Asynchronous Client

import asyncio
from labs import AsyncLabsApiClient

async def main():
    async with AsyncLabsApiClient() as client:
        bots = await client.list_bots(limit=5)
        print(bots)

asyncio.run(main())

Client options

Both LabsApiClient and AsyncLabsApiClient accept the same options and expose the same methods. Close clients with a with / async with block or call close().

Authentication

Public endpoints do not require an API key.

For authenticated requests, configure LABS_API_KEY in your environment:

PowerShell

$env:LABS_API_KEY = "YOUR_API_KEY"

Linux/macOS

export LABS_API_KEY="YOUR_API_KEY"

Or provide the key directly:

from labs import LabsApiClient

client = LabsApiClient(api_key="YOUR_API_KEY")

Never expose your API key in client-side applications or public repositories.

API examples

List bots

with LabsApiClient() as client:
    result = client.list_bots(limit=10)
    print(result)

Get a bot

with LabsApiClient() as client:
    result = client.get_bot_by_id("YOUR_BOT_ID")
    print(result)

List users

with LabsApiClient() as client:
    result = client.list_users(limit=10)
    print(result)

Website statistics

with LabsApiClient() as client:
    result = client.get_website_stats()
    print(result)

Post bot stats

with LabsApiClient() as client:
    # Supports guild_count, server_count, and serverCount aliases
    result = client.post_stats(
        bot_id="YOUR_BOT_ID",
        server_count=100,
        user_count=5000,
    )
    print(result)

Stats submission requires appropriate API permissions.

Generic requests

with LabsApiClient() as client:
    result = client.get("/custom", params={"q": "search"})
    print(result)

Authenticated request:

with LabsApiClient() as client:
    result = client.post(
        "/admin",
        body={"action": "rebuild"},
        authenticated=True,
    )

Paths must start with a single / and must not contain a query string; pass query values through params. The async client exposes the same helpers as coroutines. Only use endpoints and request bodies supported by your API credentials and documentation.

Error handling

LabsAPIError is the base class. LabsAPIAuthError covers 401 or a missing key, LabsAPIPermissionError covers 403, LabsAPIRateLimitError covers 429, LabsAPIRequestError covers other HTTP errors and LabsAPIConnectionError covers timeouts and network failures. Every error exposes status_code, code, retry_after and response.

from labs import (
    LabsApiClient,
    LabsAPIError,
    LabsAPIRateLimitError,
)

try:
    with LabsApiClient() as client:
        result = client.list_bots()
        print(result)

except LabsAPIRateLimitError as exc:
    print("Rate limited:", exc.retry_after)

except LabsAPIError as exc:
    print("Labs API error:", exc)

Telemetry

This client sends a small set of telemetry headers by default to identify the SDK and runtime to your API: X-SDK-Name, X-SDK-Version, X-SDK-Lang and X-SDK-Instance-Id (a random UUID generated once per client).

To disable telemetry, pass telemetry=False when creating the client:

client = LabsApiClient(telemetry=False)

Development

python -m pip install -e .
python -m pip install pytest
python -m pytest -q

License

MIT