> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryprofound.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Python SDK

> Install and use the official Python SDK for the Profound API

The Python SDK is published on PyPI as [profound](https://pypi.org/project/profound/).

## Installation

```bash Install the package wrap theme={null}
pip install profound
```

## Quick start

```python Create a client and run a report expandable wrap theme={null}
from profound import Profound

client = Profound(
    api_key="your-api-key-here"  # or set PROFOUND_API_KEY env var
)

# Get organization categories
categories = client.organizations.categories.list()
print(categories)

# Generate a report
report = client.reports.visibility(
    category_id=categories[0]['id'],
    start_date="2024-01-01",
    end_date="2024-01-31",
    dimensions=["asset_name"],
    metrics=["visibility_score"]
)
print(report)
```

## Authentication

The SDK reads your API key from either of these sources:

1. **Environment variable** (recommended): set `PROFOUND_API_KEY` in your environment.
2. **Constructor parameter**: pass `api_key` when initializing the client.

```bash Set the environment variable wrap theme={null}
export PROFOUND_API_KEY="your-api-key-here"
```

For details on obtaining an API key, see [Authentication](/rest-api/authentication).

## Error handling

```python Catch API errors expandable wrap theme={null}
from profound import Profound, APIError

client = Profound()

try:
    report = client.reports.visibility(
        category_id="invalid-id",
        start_date="2024-01-01",
        end_date="2024-01-31",
        dimensions=["asset_name"],
        metrics=["visibility_score"]
    )
except APIError as e:
    print(f"API Error: {e.status_code} - {e.message}")
```

## Rate limiting

The API has a default limit of 600 requests per hour per API key. When you exceed this limit, you receive a `429 Too Many Requests` error. The SDK raises an error that you can catch and handle.

```python Handle rate limits wrap theme={null}
from profound import RateLimitError

try:
    report = client.reports.visibility(...)
except RateLimitError as e:
    print("Rate limit exceeded. Please wait before retrying.")
```

## Async support

The SDK supports both synchronous and asynchronous usage:

```python Synchronous and asynchronous clients expandable wrap theme={null}
# Synchronous
from profound import Profound
client = Profound()
categories = client.organizations.categories.list()

# Asynchronous
from profound import AsyncProfound
import asyncio

async def main():
    client = AsyncProfound()
    categories = await client.organizations.categories.list()

asyncio.run(main())
```

## Code examples

Every endpoint in the API documentation includes working Python samples. Browse the **Endpoints** section in the REST API & SDKs tab for examples covering:

* Organization management
* Category discovery
* Report generation
* Raw data access

<Tip>
  SDK interfaces may change as we improve the API. Pin to a specific version in production environments.
</Tip>