Saltar al contenido principal

Autenticación

Cada solicitud necesita tu clave de API en el encabezado X-API-Key. El SDK de Python la lee de la variable de entorno PROFOUND_API_KEY.
Genera una clave en la aplicación, en Settings → API Keys. Trátala como una contraseña: tiene acceso completo a los datos de tu organización, incluidos los endpoints de escritura, como crear prompts y ejecutar agentes.

Límite de solicitudes

600 solicitudes por hora, por clave. Cualquier exceso devuelve 429 Too Many Requests. Almacena las respuestas en caché siempre que puedas y agrupa las consultas de comparación entre períodos o de varios activos en lugar de dispersarlas en muchas llamadas.

end_date es exclusivo: suma un día

end_date se interpreta al inicio de ese día en hora del Este (ET), por lo que queda excluido de la respuesta. Para incluir todo el May 10, envía end_date="2026-05-11". Los intervalos de date_interval ("hour" / "day" / "week" / "month" / "quarter" / "year" / "relative_week") también se calculan en ET. Las semanas empiezan el domingo.

Lee las posiciones de las columnas en info.query, no en tu solicitud

Cada fila de la respuesta agrupa sus metrics y dimensions como arreglos. El orden de los valores en esos arreglos es el que aparece en info.query.metrics e info.query.dimensions, que reflejan tu solicitud. Busca las posiciones ahí en lugar de codificarlas de forma fija:
Una respuesta siempre tiene este aspecto:

Las variaciones entre períodos se calculan del lado del cliente

La API no devuelve el cambio frente al período anterior. Ejecuta la misma llamada dos veces (ventana actual y una ventana anterior de igual duración) y resta.

No promedies filas diarias para obtener una puntuación del período

Una llamada con dimensions=["date"] devuelve una fila por día. Una llamada sin date devuelve una fila para toda la ventana. Son números diferentes: la puntuación del período está ponderada por tráfico, y un promedio de filas diarias no lo está. Usa la llamada sin date para los valores principales y la llamada con date para los gráficos. Nunca derives uno del otro.

Paginación

El valor predeterminado de pagination.limit es 10,000. El máximo es 50,000. Usa info.total_rows (que se devuelve en cada respuesta) para decidir si necesitas paginar. Casi todas las consultas caben en una sola página de 50k; solo las consultas de citas pesadas con dimensions=["url", ...] suelen necesitar una segunda página.
Si necesitas más, incrementa offset en limit hasta cubrir total_rows.

Filtros

Cada endpoint de informes acepta un arreglo filters de objetos {field, operator, value}:
Los filtros de UUID (model_id, region_id, topic_id, tag_id, persona_id) solo aceptan is, not_is, in y not_in. Los operadores de subcadena y de expresión regular se aplican a campos basados en nombres, como asset_name, root_domain y url. prompt_type (con valores como "visibility") corresponde al filtro Prompt Type de la aplicación. Envía prompt_type=visibility en las consultas de Citations para reflejar el alcance predeterminado de la interfaz. prompt_type está obsoleto en favor de analysis_type (valores visibility, sentiment, sentiment_v2, accuracy); por ahora se aceptan ambos.

Respuestas de error

Zonas horarias

Toda la agrupación por intervalos se realiza en hora del Este (ET). Un rango de “últimos 7 días” anclado a tu reloj local puede caer en un día ET distinto del que esperas. Ancla los trabajos programados a ET: