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

# SDK de Python

> Instala y usa el SDK oficial de Python para la API de Profound

El SDK de Python está publicado en PyPI como [profound](https://pypi.org/project/profound/).

## Instalación

```bash Install the package wrap theme={null}
pip install profound
```

## Inicio rápido

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

## Autenticación

El SDK lee tu clave de API desde cualquiera de estas fuentes:

1. **Variable de entorno** (recomendado): define `PROFOUND_API_KEY` en tu entorno.
2. **Parámetro del constructor**: pasa `api_key` al inicializar el cliente.

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

Para obtener más detalles sobre cómo conseguir una clave de API, consulta [Autenticación](https://docs.tryprofound.com/es/rest-api/authentication.md).

## Manejo de errores

```python Catch API errors expandable wrap 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}")
```

## Límites de solicitudes

La API tiene un límite predeterminado de 600 solicitudes por hora por clave de API. Cuando superas este límite, recibes un error `429 Too Many Requests`. El SDK lanza un error que puedes capturar y manejar.

```python Handle rate limits wrap theme={null}
from profound import RateLimitError

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

## Compatibilidad asíncrona

El SDK admite tanto el uso síncrono como el asíncrono:

```python Synchronous and asynchronous clients expandable wrap 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())
```

## Ejemplos de código

Cada endpoint de la documentación de la API incluye ejemplos funcionales en Python. Explora la sección **Endpoints** en la pestaña REST API y SDKs para ver ejemplos de:

* Administración de organizaciones
* Descubrimiento de categorías
* Generación de informes
* Acceso a datos sin procesar

> [!TIP]
>
> Las interfaces del SDK pueden cambiar a medida que mejoramos la API. Fija una versión específica en entornos de producción.
