Se lavori sulla generative engine optimization (GEO), ti servono dati su cosa dicono le risposte dell’AI: quali domande citano il tuo dominio, quanto spesso il tuo brand compare accanto ai concorrenti, di quali siti l’AI si fida per la tua categoria e cosa scrive Google AI Mode per una ricerca. Il 2026-11-17 SocQ ha aggiunto quattro endpoint per questo scopo nella nuova piattaforma AI Search. Questa guida spiega cosa restituisce ciascuno, la richiesta, il prezzo e quando usarlo.
Risposta rapida: invia un dominio (
target) o una parola chiave (query) aPOST /v1/ai-search/llm-mentions,/llm-brand-metricso/llm-top-mentionedper leggere le risposte di AI Overviews o ChatGPT. Invia una ricerca aPOST /v1/ai-search/google-ai-modeper ottenere una risposta di AI Mode con le sue fonti. InterrogaGET /v1/tasks/{task_id}per i risultati.
I nuovi endpoint AI Search
1 credito SocQ = $0.005.
| Endpoint | Cosa restituisce | Prezzo |
|---|---|---|
| LLM Mentions API | Una riga per ogni risposta AI che cita un dominio o menziona una parola chiave: la domanda, la risposta completa in Markdown, le fonti citate e il volume di ricerca AI | 40 crediti ($0.20) per richiesta + 0.5 crediti ($0.0025) per risposta |
| AI Search Visibility API | Il totale delle risposte AI che menzionano un dominio o una parola chiave, poi le suddivisioni per domini citati, domini dei risultati web e (su ChatGPT) brand e categorie di brand | 40 crediti ($0.20) per richiesta + 0.5 crediti ($0.0025) per riga |
| LLM Top Sources API | I dieci domini o pagine più citati dalle risposte AI per una parola chiave o un dominio, ordinati per menzioni | 40 crediti ($0.20) per richiesta + 0.5 crediti ($0.0025) per dominio o pagina in classifica |
| Google AI Mode API | La risposta completa di Google AI Mode per una ricerca in Markdown, con tutte le fonti citate | 2 crediti ($0.01) per richiesta |
Per i tre endpoint LLM la quota base di 40 crediti si applica anche quando non viene trovato nulla.
Autenticazione e flusso asincrono dei task
Tutte le richieste SocQ si autenticano con una chiave API nell’header Authorization, e lo stesso header si usa per l’invio, lo stato del task e la lettura dei risultati:
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Ogni raccolta viene eseguita come task in background:
submit -> task_id -> queued -> running -> succeeded
\-> failed
La risposta all’invio contiene data.task_id e data.status. Interroga l’endpoint dei task con quell’ID:
curl "https://api.socq.ai/v1/tasks/$TASK_ID?limit=50" \
-H "Authorization: Bearer $SOCQ_API_KEY"
Quando status è succeeded, la risposta include la prima pagina di record normalizzati in data.results.items. limit vale 50 per impostazione predefinita e arriva fino a 500. Se has_more è true, passa results.next_cursor come cursor per leggere la pagina successiva. Finché un task è queued, running o failed, l’endpoint restituisce i metadati del task senza results.
Un callback_url facoltativo nel corpo dell’invio fa sì che SocQ mandi una POST con il riepilogo del task quando termina; leggi i record con GET /v1/tasks/{task_id}. Un timeout lato client non annulla il task, quindi riprendi con lo stesso ID invece di pagare un duplicato. 402 significa crediti insufficienti; 429 significa che la chiave ha raggiunto un limite di frequenza o di crediti.
LLM Mentions API: le risposte che ti citano
La LLM Mentions API elenca le domande in cui Google AI Overviews o ChatGPT citano il tuo dominio, oppure in cui il tuo brand o la tua parola chiave compare nella risposta. Indica un dominio in target o una parola chiave in query, non entrambi. platform può essere google (AI Overviews, il valore predefinito) o chat_gpt, monitorato per gli Stati Uniti in inglese. results_limit vale 100 per impostazione predefinita e accetta valori da 1 a 1.000.
curl -X POST "https://api.socq.ai/v1/ai-search/llm-mentions" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"target": "notion.so",
"platform": "google",
"results_limit": 100
}'
Ogni riga è una domanda con la relativa risposta. I campi che userai di più:
questioneanswer: la domanda e la risposta completa in Markdown.ai_search_volume: numero mensile stimato di volte in cui la domanda viene posta.sources: pagine citate conposition,title,url,domain,sourceetext.search_resultsebrands: risultati web consultati dall’AI e brand che ha nominato (solo ChatGPT).fan_out_queries: ricerche di approfondimento eseguite dall’AI.first_seen_atelast_seen_at: quando la risposta è stata registrata per la prima e l’ultima volta.
Usala per verificare la copertura GEO, trovare le pagine di cui l’AI si fida nella tua nicchia o individuare risposte che descrivono il tuo prodotto in modo sbagliato. 100 risposte costano 90 crediti ($0.45). Consulta la documentazione di LLM Mentions per tutti i campi.
AI Search Visibility API: la share of voice nelle risposte AI
La AI Search Visibility API è un report di share of voice. La prima riga è il numero totale di risposte AI che menzionano il tuo dominio o la tua parola chiave e il volume mensile di ricerca AI che le genera. Seguono fino a 10 righe per ogni suddivisione: i domini più citati nelle risposte, i domini nei risultati web consultati dall’AI e, su chat_gpt, i brand e le categorie di brand nominati nelle stesse risposte.
curl -X POST "https://api.socq.ai/v1/ai-search/llm-brand-metrics" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"target": "hubspot.com",
"platform": "chat_gpt"
}'
Ogni riga ha una dimension (total, source_domain, search_result_domain, brand o brand_category), un name, un rank all’interno della sua dimensione, mentions_count e ai_search_volume. Eseguila per il tuo brand e per due concorrenti per confrontare chi viene consigliato dall’AI. Un report ChatGPT con il totale e quattro suddivisioni complete è di 41 righe, ovvero 60.5 crediti ($0.3025). Riferimento dei campi: documentazione di AI Search Visibility.
LLM Top Sources API: i siti che l’AI cita per un argomento
La LLM Top Sources API risponde a un’altra domanda: quali siti cita l’AI quando le persone chiedono informazioni sulla tua categoria? Indica una parola chiave in query o un dominio in target. Imposta content_type su domains (il valore predefinito) o pages. results_limit vale 10 per impostazione predefinita, che è anche il massimo.
curl -X POST "https://api.socq.ai/v1/ai-search/llm-top-mentioned" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"query": "crm software",
"platform": "google",
"content_type": "domains"
}'
Le righe usano la stessa struttura di metriche di AI Search Visibility, con dimension impostato su domain o page. La vista per pagine è una shortlist pronta per le attività di digital PR. Dieci righe in classifica costano 45 crediti ($0.225). Dettagli: documentazione di LLM Top Sources.
Google AI Mode API: una risposta completa con le fonti
AI Mode è la scheda conversazionale di Google Search che scrive una risposta completa invece di elencare link. La Google AI Mode API accetta una query e restituisce quella risposta in Markdown, più un elenco deduplicato delle fonti citate. I valori predefiniti sono Stati Uniti (location_code 2840) e inglese (language_code en); modificali per confrontare le risposte tra paesi e lingue.
curl -X POST "https://api.socq.ai/v1/ai-search/google-ai-mode" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"query": "best crm for startups",
"location_code": 2840,
"language_code": "en"
}'
Ogni richiesta restituisce una riga con query, answer, references (posizione, titolo, URL, dominio, fonte ed estratto), location_code, language_code e l’url della pagina di AI Mode. A 2 crediti ($0.01) per ricerca è un modo economico per verificare se le tue pagine sono tra le fonti delle ricerche che ti interessano. Consulta la documentazione di Google AI Mode.
Quale endpoint usare
- "Quali risposte AI ci menzionano e cosa dicono?" Usa LLM Mentions.
- "Quanto siamo visibili nelle risposte AI rispetto ai concorrenti?" Usa AI Search Visibility, una volta per dominio.
- "A quali siti dovremmo proporci perché l’AI ci citi?" Usa LLM Top Sources con
content_type: "pages". - "Cosa dice Google AI Mode per questa ricerca esatta, in questo mercato?" Usa Google AI Mode.
Un ordine tipico è LLM Top Sources per la categoria, AI Search Visibility per te e i tuoi concorrenti, poi LLM Mentions per leggere le risposte dietro i numeri. Per i ranking classici, vedi la piattaforma SEO.
FAQ
Cos’è un’API di ricerca AI?
Un’API che restituisce cosa dicono i motori di risposta basati sull’AI invece di un elenco di link. La versione di SocQ copre le risposte di AI Overviews e ChatGPT che menzionano un dominio o una parola chiave, le metriche di visibilità, le fonti più citate e le risposte complete di Google AI Mode.
Quali piattaforme AI sono coperte?
I tre endpoint LLM accettano platform impostato su google (AI Overviews, il valore predefinito) o chat_gpt. ChatGPT è monitorato per gli Stati Uniti in inglese. Le righe di brand e categorie di brand, i risultati web dell’AI e gli elenchi di brand compaiono solo con chat_gpt.
Posso inviare un dominio e una parola chiave nella stessa richiesta?
No. LLM Mentions, AI Search Visibility e LLM Top Sources accettano target (un dominio) oppure query (una parola chiave), non entrambi. Esegui due richieste se ti servono entrambe le viste.
Mi viene addebitato qualcosa se non viene trovata nessuna risposta AI?
Sì, per i tre endpoint LLM la quota base di 40 crediti si applica anche quando non viene trovato nulla; i crediti per risultato si applicano solo alle righe restituite. Google AI Mode costa 2 crediti per richiesta.
Quanto costa un tipico audit GEO?
Una richiesta LLM Top Sources (45 crediti), tre report di visibilità su ChatGPT (fino a 60.5 crediti ciascuno) e una richiesta LLM Mentions da 100 risposte (90 crediti) arrivano al massimo a 316.5 crediti, circa $1.58. I prezzi possono cambiare, quindi controlla prima le pagine degli endpoint.
AI SEARCH API
Prova il flusso di lavoro con un URL pubblico di AI Search
Invia input pubblici e ricevi record normalizzati con un contesto di origine tracciabile.
Scopri le API di AI Search