SDKs

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

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.

Installation

pip install profound

npm install @profoundai/client
# or
yarn add @profoundai/client
# or
pnpm add @profoundai/client
# or
bun add @profoundai/client

Quick Start

Python

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

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:

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

# Set environment variable
export PROFOUND_API_KEY="your-api-key-here"

For more details on obtaining an API key, see Authentication.

Error Handling

Python

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

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
from profound import RateLimitError

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

// 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:

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

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
JavaScript Package: npm
API Documentation: REST API Introduction
Support: support@tryprofound.com

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

Overview

Integrations

Example Requests

Agents

Organization

Categories

Answers

Reports

Content Optimization

SDKs

Overview

Installation

Quick Start

Python

JavaScript/TypeScript

Authentication

Error Handling

Python

JavaScript/TypeScript

Rate Limiting

Async Support

Python

JavaScript

Code Examples

Support & Resources

​Overview

​Installation

​Quick Start

​Python

​JavaScript/TypeScript

​Authentication

​Error Handling

​Python

​JavaScript/TypeScript

​Rate Limiting

​Async Support

​Python

​JavaScript

​Code Examples

​Support & Resources

Overview

Installation

Quick Start

Python

JavaScript/TypeScript

Authentication

Error Handling

Python

JavaScript/TypeScript

Rate Limiting

Async Support

Python

JavaScript

Code Examples

Support & Resources