> ## 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.

# SDKs

> Official Python and JavaScript SDKs for the Profound API

## Overview

Profound provides official SDKs for Python and JavaScript/TypeScript, making it easier to integrate our API into your applications.

**Key benefits:**

* Type-safe interfaces with full TypeScript support
* Automatic authentication handling
* Built-in retry logic and error handling
* Comprehensive code examples for every endpoint
* Async/await support for modern applications

<Note>
  All API endpoint documentation includes code samples in both Python and JavaScript. View the **Endpoints** section in the REST API tab to see examples for specific operations.
</Note>

## Installation

<CodeGroup>
  ```bash Python theme={null}
  pip install profound
  ```

  ```bash JavaScript theme={null}
  npm install @profoundai/client
  # or
  yarn add @profoundai/client
  # or
  pnpm add @profoundai/client
  # or
  bun add @profoundai/client
  ```
</CodeGroup>

## Quick Start

### Python

```python 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)
```

### JavaScript/TypeScript

```typescript theme={null}
import Profound from '@profoundai/client';

const client = new Profound({
  apiKey: "your-api-key-here" // or set PROFOUND_API_KEY env var
});

// Get organization categories
const categories = await client.organizations.categories.list();
console.log(categories);

// Generate a report
const report = await client.reports.visibility({
  category_id: categories[0].id,
  start_date: "2024-01-01",
  end_date: "2024-01-31",
  dimensions: ["asset_name"],
  metrics: ["visibility_score"]
});
console.log(report);
```

## Authentication

Both SDKs support multiple authentication methods:

1. **Environment variable** (recommended): Set `PROFOUND_API_KEY` in your environment
2. **Constructor parameter**: Pass `api_key` (Python) or `apiKey` (JavaScript) when initializing the client

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

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

## Error Handling

### Python

```python 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}")
```

### JavaScript/TypeScript

```typescript theme={null}
import Profound from '@profoundai/client';

const client = new Profound();

try {
  const report = await client.reports.visibility({
    category_id: 'invalid-id',
    start_date: '2024-01-01',
    end_date: '2024-01-31',
    dimensions: ['asset_name'],
    metrics: ['visibility_score']
  });
} catch (error) {
  if (error instanceof Profound.APIError) {
    console.error(`API Error: ${error.status} - ${error.message}`);
  }
}
```

## Rate Limiting

The API has a default limit of 600 requests per hour per API key. When you exceed this limit, you'll receive a `429 Too Many Requests` error. Both SDKs will throw an error that you can catch and handle appropriately.

```python theme={null}
# Python
from profound import RateLimitError

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

```typescript theme={null}
// JavaScript
import Profound from '@profoundai/client';

try {
  const report = await client.reports.visibility(...);
} catch (error) {
  if (error instanceof Profound.RateLimitError) {
    console.log('Rate limit exceeded. Please wait before retrying.');
  }
}
```

## Async Support

### Python

The Python SDK supports both synchronous and asynchronous usage:

```python 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())
```

### JavaScript

The JavaScript SDK is fully async/await based:

```typescript theme={null}
import Profound from '@profoundai/client';

const client = new Profound();

// All methods return promises
const categories = await client.organizations.categories.list();
```

## Code Examples

Every endpoint in our API documentation includes working code samples for both SDKs. Browse the **Endpoints** section in the REST API tab to see specific examples for:

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

## Support & Resources

* **Python Package**: [PyPI](https://pypi.org/project/profound/)
* **JavaScript Package**: [npm](https://www.npmjs.com/package/@profoundai/client)
* **API Documentation**: [REST API Introduction](/rest-api/introduction)
* **Support**: [support@tryprofound.com](mailto:support@tryprofound.com)

<Warning>
  SDK interfaces may change as we improve the API. We recommend pinning to specific versions in production environments.
</Warning>