Skip to main content

​
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

​
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';

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
# 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';

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';

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';

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

The API is currently in beta phase. SDK interfaces may change as we improve the API. We recommend pinning to specific versions in production environments.
⌘I