Berichte-API

Ein KI-Bericht liest eine Reihe abgeschlossener Gespräche und beschreibt die Stimmung, die häufigsten Themen und die Probleme. Die API gibt die Berichte zurück, die dein Team im Dashboard erstellt hat. Neue Berichte kann sie nicht erstellen. Authentifizierung, Paginierung und Fehler sind im API-Überblick beschrieben.

Berichte auflisten#

HTTP

GET /api/v1/projects/{project_id}/reports

Gibt die Berichte eines Projekts zurück, die neuesten zuerst, ohne ihren Inhalt. Gelöschte Berichte sind nicht enthalten.

Query-Parameter#

Parameter	Beschreibung
`status`	Einer oder mehrere der Werte `generating`, `completed`, `failed`, durch Kommas getrennt
`limit`	1 bis 100. Standard `25`.
`cursor`	Der `next_cursor` der vorherigen Seite

Beispiel#

curl -G "https://diaform.io/api/v1/projects/b8acb3ab-1f3d-4a7e-a846-b7f493f86b6d/reports" \
  -H "Authorization: Bearer $DIAFORM_API_KEY" \
  --data-urlencode "status=completed"

Antwort#

JSON

{
  "data": [
    {
      "id": "882f2ed7-07d9-4344-aced-9e523275b196",
      "project_id": "b8acb3ab-1f3d-4a7e-a846-b7f493f86b6d",
      "status": "completed",
      "title": "Support problems overshadow a well-liked product",
      "focus": null,
      "selection": {
        "mode": "date_range",
        "range_start": "2026-05-01T00:00:00+00:00",
        "range_end": "2026-05-31T23:59:59+00:00"
      },
      "conversation_count": 48,
      "first_conversation_at": "2026-05-01T08:12:09.692998+00:00",
      "last_conversation_at": "2026-05-30T13:11:09.628765+00:00",
      "sentiment_counts": {
        "positive": 14,
        "negative": 11,
        "neutral": 8,
        "mixed": 15,
        "unknown": 0
      },
      "error_message": null,
      "created_at": "2026-06-01T09:33:49.465144+00:00",
      "completed_at": "2026-06-01T09:34:07.2+00:00"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Felder eines Berichts#

Feld	Typ	Beschreibung
`id`	string	ID des Berichts
`project_id`	string	Das Projekt, zu dem er gehört
`status`	string	`generating`, `completed` oder `failed`
`title`	string oder null	Die Überschrift, die die KI dem Bericht gegeben hat. `null`, bis er fertig ist.
`focus`	string oder null	Die Frage, die dein Team dem Bericht als Schwerpunkt mitgegeben hat, falls es eine gab
`selection.mode`	string	`date_range` (alle abgeschlossenen Gespräche eines Zeitraums) oder `manual` (einzeln ausgewählte Gespräche)
`selection.range_start`, `selection.range_end`	string oder null	Der Zeitraum bei `date_range`. `null` heißt, dass es auf dieser Seite keine Grenze gibt.
`conversation_count`	number	Wie viele Gespräche der Bericht umfasst
`first_conversation_at`, `last_conversation_at`	string oder null	Wann das älteste und das neueste erfasste Gespräch erstellt wurden
`sentiment_counts`	object oder null	Die erfassten Gespräche nach Gesamtstimmung. `null`, bis der Bericht fertig ist.
`error_message`	string oder null	Warum ein Bericht mit dem Status `failed` fehlgeschlagen ist
`created_at`	string	Wann der Bericht angefordert wurde
`completed_at`	string oder null	Wann er fertig wurde oder fehlgeschlagen ist

Bericht abrufen#

HTTP

GET /api/v1/reports/{report_id}

Gibt einen Bericht mit jedem Feld der Liste zurück, dazu conversation_ids und den geschriebenen content.

Beispiel#

curl "https://diaform.io/api/v1/reports/882f2ed7-07d9-4344-aced-9e523275b196" \
  -H "Authorization: Bearer $DIAFORM_API_KEY"

Antwort#

Die Felder, die auch in der Liste vorkommen, sind hier weggelassen.

JSON

{
  "id": "882f2ed7-07d9-4344-aced-9e523275b196",
  "status": "completed",
  "title": "Support problems overshadow a well-liked product",
  "conversation_ids": [
    "0f8d43a2-6df9-49c8-bf5d-fd2b6ec2d9ee",
    "912b8ced-f69d-4f50-b497-9a712fe59359"
  ],
  "content": {
    "summary": "Most respondents like the product and would recommend it, but support wait times came up in a quarter of the interviews.",
    "focus_answer": null,
    "sentiment_explanation": "Praise for the product is offset by frustration with support.",
    "themes": [
      {
        "title": "Customer support is the top complaint",
        "detail": "Twelve respondents described long waits before reaching support.",
        "tone": "negative",
        "mention_count": 12,
        "conversation_ids": ["912b8ced-f69d-4f50-b497-9a712fe59359"],
        "quotes": [
          {
            "conversation_id": "912b8ced-f69d-4f50-b497-9a712fe59359",
            "text": "it took me 25 min to connect last time, which is too long",
            "translation": null,
            "respondent_label": "alex@acme.com",
            "created_at": "2026-05-10T17:52:10.539708+00:00"
          }
        ]
      }
    ],
    "issues": [
      {
        "title": "Invite emails land in spam",
        "detail": "Three respondents never received their teammate invite.",
        "severity": "high",
        "mention_count": 3,
        "conversation_ids": ["0f8d43a2-6df9-49c8-bf5d-fd2b6ec2d9ee"],
        "quotes": []
      }
    ],
    "outliers": [
      {
        "title": "Request for an on-premise version",
        "detail": "One enterprise respondent can't use cloud tools.",
        "mention_count": 1,
        "conversation_ids": ["0f8d43a2-6df9-49c8-bf5d-fd2b6ec2d9ee"]
      }
    ]
  }
}

Felder des Inhalts#

content ist null, solange der Bericht den Status generating hat, und auch beim Status failed.

Feld	Typ	Beschreibung
`conversation_ids`	array	Jedes Gespräch, das der Bericht umfasst
`content.summary`	string	Die Gesamtzusammenfassung des Berichts
`content.focus_answer`	string oder null	Die Antwort auf den `focus` des Berichts, falls einer gesetzt wurde
`content.sentiment_explanation`	string	Was die Verteilung der Stimmung erklärt
`content.themes`	array	Wiederkehrende Themen, die am häufigsten genannten zuerst
`content.themes[].tone`	string	`positive`, `negative`, `mixed` oder `neutral`
`content.issues`	array	Konkrete Probleme, die behoben werden sollten
`content.issues[].severity`	string	`high`, `medium` oder `low`
`content.outliers`	array	Auffällige Punkte, die nur wenige Teilnehmer angesprochen haben. Sie haben keine Zitate.
`title`, `detail`	string	Bei jedem Thema, Problem und Ausreißer: eine Überschrift und eine kurze Erklärung
`mention_count`	number	In wie vielen Gesprächen es angesprochen wurde
`conversation_ids`	array	Diese Gespräche. Ruf jedes davon mit der Gespräche-API ab.
`quotes[].text`	string	Die eigenen Worte des Teilnehmers
`quotes[].translation`	string oder null	Eine englische Übersetzung, wenn das Zitat in einer anderen Sprache ist
`quotes[].conversation_id`	string	Das Gespräch, aus dem das Zitat stammt
`quotes[].respondent_label`	string oder null	Wer es gesagt hat, falls bekannt
`quotes[].created_at`	string	Wann dieses Gespräch erstellt wurde

Ein Bericht ist eine Momentaufnahme der Gespräche zu dem Zeitpunkt, zu dem er geschrieben wurde. Wird ein Gespräch später gelöscht, werden seine Zitate aus dem Bericht entfernt.