> ## Documentation Index
> Fetch the complete documentation index at: https://docs.heify.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Configuration Analysis
> Generates an AI-powered analytics report for all completed transcriptions under a configuration.
The AI output language is controlled by `analytics_language` on the [Configuration](/core/configuration#analytics-language). Set it to `"df"` for auto-detection based on the most prevalent transcription language.
This endpoint has a **monthly call limit**. The counter resets automatically on the first call of a new month. Exceeding the limit returns `429 Too Many Requests`.
Only **completed** transcriptions are included in the analysis. Pending, processing, or failed transcriptions are excluded.
If no completed transcriptions exist for the configuration, the endpoint returns `200 OK` with `{"data": {"message": "No completed transcriptions found to analyze."}}` — not an error.
The `actionable_insights` and `executive_narrative` fields in `ai_insights` are **Markdown-formatted strings**, not structured objects. Render them accordingly.
## OpenAPI
````yaml api-reference/openapi-configurations.json POST /analytics
openapi: 3.1.0
info:
title: Heify API — Configurations
description: Endpoints for creating, retrieving, and deleting Configurations.
version: 1.0.0
servers:
- url: https://api.heify.com
security:
- apiKeyAuth: []
paths:
/analytics:
post:
summary: Configuration Analysis
description: >-
Generates a comprehensive analytics report — statistical analysis plus
AI-powered insights (via Google Gemini) — for all completed
transcriptions under a specific configuration. Subject to a monthly call
limit per account.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AnalyticsRequest'
examples:
AnalyticsExample:
summary: Request analytics for a configuration
value:
configuration_id: a1b2c3d4-e5f6-7890-1234-567890abcdef
responses:
'200':
description: Analytics report generated successfully, or no data found.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/AnalyticsResponse'
- $ref: '#/components/schemas/AnalyticsNoDataResponse'
examples:
AnalyticsSuccess:
summary: Analytics report with data
value:
data:
configuration_details:
id: a1b2c3d4-e5f6-7890-1234-567890abcdef
tag: Customer Support Campaign
total_audios_analyzed: 150
ai_insights:
actionable_insights: |-
# Top 3 Acciones Inmediatas
## 1. Mejorar el tiempo de resolución...
executive_narrative: |-
# Contexto Actual
Hemos analizado 150 llamadas de soporte...
detailed_analysis:
metadata_analysis:
duration_stats:
total_seconds: 54000
average_seconds: 360
min_seconds: 45
max_seconds: 1800
histogram:
0-60: 5
60-120: 18
120-180: 42
speaker_stats:
average_per_audio: 2.1
total_distribution:
'1': 20
'2': 98
'3': 32
language_distribution:
es: 120
en: 30
extracted_fields_analysis:
sentiment_analysis:
type: string
stats:
total_count: 150
valid_count: 148
missing_count: 2
value_counts:
POSITIVE: 89
NEGATIVE: 42
NEUTRAL: 17
total_unique_categories: 3
timeseries_analysis:
'2026-03-20':
audio_count: 15
advanced_analysis: {}
NoData:
summary: No completed transcriptions found
value:
data:
message: No completed transcriptions found to analyze.
'429':
description: Monthly analytics call limit reached.
content:
application/json:
example:
error:
message: >-
Monthly analytics call limit reached. Please try again next
month or upgrade your plan.
code: 429
components:
schemas:
AnalyticsRequest:
type: object
properties:
configuration_id:
type: string
format: uuid
description: >-
The configuration whose completed transcriptions to analyze. Must
belong to the authenticated client.
required:
- configuration_id
AnalyticsResponse:
type: object
properties:
data:
type: object
properties:
configuration_details:
type: object
properties:
id:
type: string
description: Configuration ID analyzed.
tag:
type: string
description: Configuration name.
total_audios_analyzed:
type: integer
description: Number of completed transcriptions included in the analysis.
ai_insights:
type: object
description: >-
AI-generated insights from Google Gemini. Both fields are
**Markdown-formatted strings**.
properties:
actionable_insights:
type: string
description: >-
Top 3-5 prioritized actions with metrics, detected risks,
growth opportunities, and key metrics to monitor. Markdown
format.
executive_narrative:
type: string
description: >-
Executive storytelling: current context, key discoveries,
recurring themes, temporal changes, and strategic
conclusion. Markdown format.
detailed_analysis:
type: object
description: Statistical breakdown of the transcriptions.
properties:
metadata_analysis:
type: object
description: >-
Audio metadata stats: `duration_stats` (total/avg/min/max
seconds + histogram), `speaker_stats` (avg per audio +
distribution), `language_distribution` (count per language
code).
extracted_fields_analysis:
type: object
description: >-
Per-field statistics keyed by field name. Each entry has the
shape `{ "type": "", "stats": { ... } }`. Stats
inside vary by type: `number` →
min/max/avg/median/sum/histogram; `boolean` →
true_count/false_count/true_percentage; `string`/`array` →
value_counts (top 30) + total_unique_categories. All types
include total_count, valid_count, missing_count.
timeseries_analysis:
type: object
description: >-
Daily aggregation keyed by `YYYY-MM-DD`. Each day has
`audio_count` and `avg_{field}` for each numeric extraction
field (`null` if no data that day).
advanced_analysis:
type: object
description: >-
Advanced statistics: `data_quality` (field completeness),
`temporal_heatmap` (activity by day-of-week and hour),
`co_occurrence` (for array fields), `correlations` (Pearson
matrix for numeric fields), `outliers` (IQR-based, up to 25
items per field).
AnalyticsNoDataResponse:
type: object
description: Returned when no completed transcriptions exist for the configuration.
properties:
data:
type: object
properties:
message:
type: string
example: No completed transcriptions found to analyze.
securitySchemes:
apiKeyAuth:
type: apiKey
in: header
name: x-api-key
````