This library provides convenient access to the profound REST API from Python.

The full API of this library can be found in api.md.

• Installation
• Usage
• API Reference
• Async
• Streaming
• Authentication
• Errors
• Client Options
• Retries and Timeouts
• Helpers
• Logging
• Requirements

pip install profound

import os

from profound import Profound

client = Profound(
    api_key=os.environ.get("PROFOUND_API_KEY"),
)

category = client.organizations.categories.list()

print(category)

The examples in the following sections assume a client configured as shown above.

See the API reference for every available operation.

Every client has an Async counterpart (AsyncProfound) exposing the same resource tree with await.

import asyncio

from profound import AsyncProfound


async def main() -> None:
    client = AsyncProfound()
    category = await client.organizations.categories.list()


asyncio.run(main())

Streaming endpoints return an async iterator that yields results as the server emits them.

stream = client.prompts.stream_answers_v2(
    category_id="7c9e6679-7425-40de-944b-e07fc1f90ae7",
    start_date="",
    end_date="",
)

for event in stream:
    print(event)

Pass credentials to the generated client constructor. Environment variables are read automatically when supported by the target runtime.

Declared schemes:

• APIKeyHeader API key in header X-API-Key
• BearerAuth bearer token

Non-success responses throw generated API errors. Error objects expose status, headers, response body, and request metadata where the target runtime supports it.

from profound import APIStatusError

try:
    category = client.organizations.categories.list()
except APIStatusError as err:
    print(err.status_code, err.message)
    raise

Documented error statuses: 422.

Configure the generated client by setting any of these options when you create it.

from profound import Profound

client = Profound(
    timeout=60.0,
    max_retries=2,
)

Generated clients support request timeouts and retry temporary failures such as network errors, 408, 409, 429, and 5xx responses. Retry delays honor Retry-After headers when present. Tune the retry and timeout client options shown above, or override them per request.

• Use client.with_raw_response.<resource>.<method>(...) to access the raw httpx.Response and parse it yourself.
• Use client.with_streaming_response.<resource>.<method>(...) to stream a response body without buffering it.

• Set the PROFOUND_LOG environment variable to info or debug to enable HTTP logging.
• Logs are emitted through the standard logging module under the profound logger.

• Python 3.8 or newer

Powered by Scalar.