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

# JavaScript SDK

> Install and use the official JavaScript and TypeScript SDK for the Profound API

The JavaScript SDK is published on npm as [@profoundai/client](https://www.npmjs.com/package/@profoundai/client). It ships with TypeScript types.

## Installation

```bash npm wrap theme={null}
npm install @profoundai/client
```

```bash yarn wrap theme={null}
yarn add @profoundai/client
```

```bash pnpm wrap theme={null}
pnpm add @profoundai/client
```

```bash bun wrap theme={null}
bun add @profoundai/client
```

## Quick start

```typescript Create a client and run a report expandable wrap 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

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 `apiKey` 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](https://docs.tryprofound.com/rest-api/authentication.md).

## Error handling

```typescript Catch API errors expandable wrap 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 receive a `429 Too Many Requests` error. The SDK throws an error that you can catch and handle.

```typescript Handle rate limits expandable wrap theme={null}
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

The SDK is fully async/await based. All methods return promises.

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

const client = new Profound();

const categories = await client.organizations.categories.list();
```

## Code examples

Every endpoint in the API documentation includes working JavaScript 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.