Zielgruppen definieren, analysieren, verstehen.

Schnellstart

Sechs Aufrufe genügen, um vom leeren Terminal zu echten Insight-Daten zu kommen. Alle Beispiele nutzen ein Beispielprojekt (public: true) — dort sind Insight-Anfragen unabhängig vom angezeigten credit_cost immer kostenlos.

1. API erreichbar? GET /health/ beantwortet ohne Authentifizierung, ob die API läuft und welche Version aktiv ist.
2. API-Key gültig? GET /whoami/ bestätigt, welchem Benutzer und welcher Organisation der Key gehört.
3. Beispielprojekt wählen. GET /projects/?public=true liefert Projekte, an denen Sie kostenlos experimentieren können. Merken Sie sich eine id sowie eine ID aus calculated_audience_ids.
4. Zielgruppe prüfen. GET /projects/{project_id}/audiences/ zeigt die berechneten Zielgruppen des Projekts inklusive Segmenten.
5. Insight auswählen. GET /insights/ listet alle verfügbaren Insights mit id, display_name und credit_cost.
6. Daten abrufen. GET /insights/{insight_id}/data/?audience_id={audience_id} liefert die eigentlichen Analyse-Daten.

Anfragemuster (gilt für alle Endpunkte)

Jeder Endpunkt außer /health/ erwartet denselben Authorization-Header. Ersetzen Sie für andere Endpunkte lediglich Methode, Pfad und ggf. den JSON-Body.

# cURL
curl -s -H "Authorization: Bearer IHR_API_KEY" \
  https://dashboard.ailon.io/public-api/v1/whoami/

# Python (requests)
import requests

response = requests.get(
    "https://dashboard.ailon.io/public-api/v1/whoami/",
    headers={"Authorization": "Bearer IHR_API_KEY"},
    timeout=30,
)
response.raise_for_status()
print(response.json())

// JavaScript (fetch)
const response = await fetch("https://dashboard.ailon.io/public-api/v1/whoami/", {
  headers: { Authorization: "Bearer IHR_API_KEY" },
});
console.log(await response.json());

Referenz für KI-Agenten

Kompakte, maschinenlesbare Zusammenfassung für LLM-gestützte Tools (Claude, ChatGPT, Copilot u. ä.), die diese API als Function-Calling-Tool oder per Browser-Zugriff nutzen. Eine reine Textversion dieser Seite steht zusätzlich unter /llms.txt bereit.

base_url:      https://dashboard.ailon.io/public-api/v1/
auth:          Header Authorization: Bearer <ailpk_...>  # bei allen Endpunkten außer /health/
format:        application/json
no_auth_endpoint: GET /health/
free_tier:      Zielgruppen in Projekten mit "public": true → alle Insight-/Summary-Anfragen kostenlos
pagination:     Query-Parameter limit + offset; Antwort enthält items, count, limit, offset
errors:         401 ungültiger Key · 402 zu wenig Credits · 403 kein Zugriff/Beispielprojekt read-only
              404 nicht gefunden · 503 Zielgruppe wird noch berechnet

# Empfohlener Ablauf für Agenten:
GET  /health/                                        # Erreichbarkeit prüfen, kein Auth nötig
GET  /whoami/                                         # Key validieren
GET  /projects/?public=true                           # kostenloses Beispielprojekt finden
GET  /projects/{project_id}/audiences/                # berechnete audience_id ermitteln
GET  /insights/                                        # insight_id + credit_cost ermitteln
GET  /insights/{insight_id}/data/?audience_id=...     # Analyse-Daten abrufen; ggf. bei status=CALCULATING erneut abfragen

Vollständige Endpunkt-Tabelle

Authentifizierung

Jede Anfrage außer GET /health/ benötigt folgenden Header:

Authorization: Bearer ailpk_….IhrGeheimerTeil

Der Key ist benutzerbezogen: Sichtbar sind ausschließlich Projekte und Zielgruppen, auf die dieser Benutzer im Dashboard Zugriff hat. Ein ungültiger oder fehlender Key führt zu 401 Unauthorized.

Kostenlose Nutzung in Beispielprojekten

Projekte mit dem Feld "public": true sind Beispielprojekte (im Dashboard: Demo-Projekte). Finden lassen sie sich über GET /projects/?public=true.

Für Einstieg und Experimente mit Insights empfiehlt sich daher ein Beispielprojekt mit bereits berechneten Zielgruppen (Feld calculated_audience_ids). In eigenen Projekten (public: false) können credit-pflichtige Endpunkte das Guthaben belasten — Details dazu im nächsten Abschnitt.

Credits & Abrechnung

Gilt ausschließlich für Zielgruppen in eigenen Projekten — Beispielprojekte sind immer kostenlos.

• Insight-Daten und Zielgruppen-Summaries können Credits kosten; die Höhe steht als credit_cost bei GET /insights/.
• Abgebucht wird ausschließlich bei erfolgreicher Antwort (status: SUCCESS) — Zwischenstände (CALCULATING) sind kostenlos.
• Das Guthaben gehört dem API-Key-Benutzer. Standardmäßig darf es nicht unter null fallen.
• Ein von Ailon festgelegtes Überziehungslimit (min_balance) ist über GET /usage/credit-limit/ einsehbar.
• Reicht das Guthaben nicht aus, antwortet die API mit 402 Payment Required.

curl -s -H "Authorization: Bearer IHR_API_KEY" \
  https://dashboard.ailon.io/public-api/v1/usage/

Pagination

Listen-Endpunkte (/projects/, /projects/{id}/audiences/, /usage/requests/, /usage/ledger/) akzeptieren limit und offset und antworten in diesem Format:

{
  "items": [ … ],
  "count": 250,
  "limit": 100,
  "offset": 0
}

Weitere Seiten laden: offset so lange erhöhen, bis offset + len(items) >= count.

Erste Schritte

{ "status": "ok", "api_version": "v1" }

{
  "user_id": 42,
  "username": "max.mustermann",
  "organisation_id": 7,
  "organisation_name": "Beispiel GmbH",
  "api_key_name": "Produktion",
  "api_key_prefix": "ailpk_abc123"
}

Projekte & Zielgruppen

Projekte enthalten Zielgruppen (Audiences) und deren Segmente. Norm-Zielgruppen werden in den Listen nicht mitgeliefert.

curl -s -H "Authorization: Bearer IHR_API_KEY" \
  "https://dashboard.ailon.io/public-api/v1/projects/?public=true&limit=10"

curl -s -X POST -H "Authorization: Bearer IHR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Sommerkampagne 2026", "description": "Neuprodukt-Launch"}' \
  https://dashboard.ailon.io/public-api/v1/projects/

curl -s -X POST -H "Authorization: Bearer IHR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Tech-affine Millennials", "prompt": "25-40 Jahre, hohe Online-Affinität"}' \
  https://dashboard.ailon.io/public-api/v1/projects/PROJECT_ID/generate_audience/

{ "potential_relative": 0.184, "potential_absolute": 1284000 }

[
  { "type": "paragraph", "data": "Diese Zielgruppe zeichnet sich durch …" }
]

Insights

Insights sind vordefinierte Analysen (z. B. demografische oder verhaltensbezogene Merkmale), die auf eine berechnete Zielgruppe angewendet werden.

[
  { "id": 1, "display_name": "Alter", "description": "…", "credit_cost": "2.00" }
]

curl -s -H "Authorization: Bearer IHR_API_KEY" \
  "https://dashboard.ailon.io/public-api/v1/insights/INSIGHT_ID/data/?audience_id=AUDIENCE_ID"

{
  "insight_id": 1, "audience_id": 55, "status": "SUCCESS", "error": null, "error_code": null,
  "data": [
    {
      "feature": { "id": 3, "display_name": "Alter" },
      "options": [
        { "option": { "id": 31, "display_name": "25-34" },
          "index_value": 142.0, "mean_pop": 0.18, "mean_audience": 0.26, "abs_audience": 331000 }
      ]
    }
  ]
}

Nutzung & Abrechnung

Status- & Fehlercodes

Zielgruppen-Status (Dashboard → API)

HTTP-Fehlercodes

Häufige Insight-error_codes

Fehlercodes aller Anfragen lassen sich zusätzlich über GET /usage/requests/ nachvollziehen.

Datenmodelle

Feldreferenz der wichtigsten Antwort- und Body-Schemas. Klappen Sie ein Modell auf, um alle Felder mit Typ und Beschreibung zu sehen.