Raportti-API

AI-raportti lukee joukon valmiita keskusteluja ja kuvaa niiden sävyn, yleiset teemat ja ongelmat. API palauttaa raportit, jotka tiimisi on luonut hallintapaneelissa. Uusia raportteja se ei voi luoda. Katso todennus, sivutus ja virheet sivulta API:n yleiskatsaus.

Listaa raportit#

HTTP

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

Palauttaa projektin raportit uusin ensin ilman niiden sisältöä. Poistetut raportit jätetään pois.

Kyselyparametrit#

Parametri	Kuvaus
`status`	Yksi tai useampi arvoista `generating`, `completed`, `failed` pilkuilla erotettuina
`limit`	1–100. Oletus `25`.
`cursor`	Edellisen sivun `next_cursor`

Esimerkki#

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

Vastaus#

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
}

Raportin kentät#

Kenttä	Tyyppi	Kuvaus
`id`	string	Raportin ID
`project_id`	string	Projekti, johon raportti kuuluu
`status`	string	`generating`, `completed` tai `failed`
`title`	string tai null	AI:n raportille antama otsikko. `null`, kunnes raportti on valmis.
`focus`	string tai null	Kysymys, johon tiimisi pyysi raporttia keskittymään, jos sellainen on
`selection.mode`	string	`date_range` (kaikki tietyn jakson valmiit keskustelut) tai `manual` (käsin valitut keskustelut)
`selection.range_start`, `selection.range_end`	string tai null	`date_range`-valinnan jakso. `null` tarkoittaa, ettei sillä puolella ole rajaa.
`conversation_count`	number	Kuinka monta keskustelua raportti kattaa
`first_conversation_at`, `last_conversation_at`	string tai null	Milloin raportin vanhin ja uusin keskustelu luotiin
`sentiment_counts`	object tai null	Raportin kattamat keskustelut yleissävyn mukaan. `null`, kunnes raportti on valmis.
`error_message`	string tai null	Miksi `failed`-tilan raportti epäonnistui
`created_at`	string	Milloin raporttia pyydettiin
`completed_at`	string tai null	Milloin se valmistui tai epäonnistui

Hae raportti#

HTTP

GET /api/v1/reports/{report_id}

Palauttaa yhden raportin, jossa on kaikki listan kentät sekä conversation_ids ja kirjoitettu sisältö kentässä content.

Esimerkki#

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

Vastaus#

Listan kanssa yhteiset kentät on jätetty tästä pois.

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"]
      }
    ]
  }
}

Sisällön kentät#

content on null, kun raportin tila on generating tai failed.

Kenttä	Tyyppi	Kuvaus
`conversation_ids`	array	Kaikki keskustelut, jotka raportti kattaa
`content.summary`	string	Raportin yleisyhteenveto
`content.focus_answer`	string tai null	Vastaus raportin `focus`-kysymykseen, jos sellainen annettiin
`content.sentiment_explanation`	string	Mikä selittää sävyjen jakauman
`content.themes`	array	Toistuvat aiheet, useimmin mainitut ensin
`content.themes[].tone`	string	`positive`, `negative`, `mixed` tai `neutral`
`content.issues`	array	Konkreettiset korjattavat ongelmat
`content.issues[].severity`	string	`high`, `medium` tai `low`
`content.outliers`	array	Huomionarvoiset asiat, jotka vain muutama vastaaja nosti esiin. Niissä ei ole lainauksia.
`title`, `detail`	string	Jokaisessa teemassa, ongelmassa ja poikkeavassa havainnossa: otsikko ja lyhyt selitys
`mention_count`	number	Kuinka monessa keskustelussa asia nousi esiin
`conversation_ids`	array	Kyseiset keskustelut. Hae mikä tahansa niistä Keskustelu-API:lla.
`quotes[].text`	string	Vastaajan omat sanat
`quotes[].translation`	string tai null	Englanninkielinen käännös, kun lainaus on muulla kielellä
`quotes[].conversation_id`	string	Keskustelu, josta lainaus on peräisin
`quotes[].respondent_label`	string tai null	Kuka sen sanoi, jos se on tiedossa
`quotes[].created_at`	string	Milloin kyseinen keskustelu luotiin

Raportti on tilannekuva keskusteluista sillä hetkellä, kun se kirjoitettiin. Jos keskustelu poistetaan myöhemmin, sen lainaukset poistetaan raportista.