Docs API

Analyseren via de API

Als aanvulling op de CRUD-endpoints voor Documenten zijn er binnen onze JSON:API ook read-endpoints beschikbaar voor threads en runs. Deze endpoints zijn vooral bedoeld voor analyse, rapportage en kwaliteitscontrole van conversaties binnen je kennisbank.

Met deze endpoints kun je complete conversaties ophalen inclusief onderliggende vragen, of juist alleen vragen opvragen en deze verfijnen met filters, sortering, includes en paginering.

Binnen deze structuur geldt:

  • een thread staat voor een volledig gesprek of conversatie

  • een run staat voor een afzonderlijke vraag-antwoordinteractie binnen dat gesprek

  • een thread kan dus meerdere runs bevatten wanneer een gebruiker vervolgvragen stelt binnen dezelfde conversatie

Deze endpoints zijn in het bijzonder bruikbaar wanneer je:

  • conversaties en vragen over een bepaalde periode wilt analyseren

  • runs wilt uitsplitsen op systeem, agent, gebruiker, feedback of moderatie-status

  • trends of kwaliteitsinzichten wilt opbouwen op basis van individuele runs

  • een thread wilt terughalen om de context van een specifieke run te beoordelen

Voordat je begint

De base-URL, de authenticatie met een Bearer-token en de vereiste headers staan op Werken met de API. De endpoints hieronder gaan daarvan uit.

Thread- en run-endpoints

Er zijn twee relevante endpoints beschikbaar:

1. Threads ophalen

GET https://{klant}.vragen.ai/api/v1/threads

Dit endpoint geeft conversaties terug op threadniveau. Een thread is de bovenliggende container van een gesprek en bevat de context van alle runs die binnen die conversatie zijn uitgevoerd.

Met include=runs kun je direct de bijbehorende runs meesturen in dezelfde response.

Als je een specifieke thread op interne JSON:API resource-ID wilt ophalen, gebruik je:

GET https://{klant}.vragen.ai/api/v1/threads/{id}

2. Runs ophalen

GET https://{klant}.vragen.ai/api/v1/runs

Dit endpoint geeft runs terug als losse records. Een run representeert doorgaans een enkele vraag met het bijbehorende antwoord binnen een thread.

Dit is bruikbaar wanneer je vooral wilt filteren op eigenschappen van individuele vragen, antwoorden, systemen, feedback of moderatie.

Als je een specifieke run op interne JSON:API resource-ID wilt ophalen, gebruik je:

GET https://{klant}.vragen.ai/api/v1/runs/{id}

Documenten ophalen die in een antwoord zijn gebruikt

Wanneer je wilt analyseren op welke bronnen een antwoord is gebaseerd, kun je bij een run ook de gebruikte documenten of documentfragmenten opvragen.

Hiervoor zijn met name de volgende includes relevant:

  • include=sources

  • include=searchables

  • include=citedSearchables

Daarbij geldt:

  • sources geeft de onderliggende bronrelaties van de run terug

  • searchables geeft de documenten of documentfragmenten terug die voor de run zijn gebruikt

  • citedSearchables geeft alleen de documenten of documentfragmenten terug die daadwerkelijk in het antwoord zijn geciteerd

Voorbeeld:

GET https://{klant}.vragen.ai/api/v1/runs/{id}?include=searchables,citedSearchables

Dit is vooral bruikbaar wanneer je:

  • wilt reconstrueren welke documenten zijn gebruikt om tot een antwoord te komen

  • alleen de geciteerde bronnen wilt tonen in een analyse- of reviewinterface

  • documentniveau en runniveau met elkaar wilt verbinden

Voorbeeld: gebruikte documenten bij een run ophalen

Onderstaand voorbeeld is gebaseerd op een echte API-call, maar de inhoud is geanonimiseerd.

Voorbeeld request:

GET https://{klant}.vragen.ai/api/v1/runs/501?include=sources,searchables,citedSearchables&fields[runs]=question,answer,sources,searchables,citedSearchables&fields[run-sources]=citation_reference,relevance_score,distance_score,is_cited&fields[semantic-searchables]=title,summary,url,relevance_score,distance

Voorbeeld response:

{
  "jsonapi": {
    "version": "1.0"
  },
  "links": {
    "self": "https://{klant}.vragen.ai/api/v1/runs/501"
  },
  "data": {
    "type": "runs",
    "id": "501",
    "attributes": {
      "question": "Wat zijn de openingstijden van het gemeentehuis?",
      "answer": "Het gemeentehuis is geopend van maandag tot en met vrijdag van 09:00 tot 17:00 uur [1]."
    },
    "relationships": {
      "sources": {
        "data": [
          {
            "type": "run-sources",
            "id": "91"
          }
        ]
      },
      "searchables": {
        "data": [
          {
            "type": "semantic-searchables",
            "id": "9001"
          }
        ]
      },
      "citedSearchables": {
        "data": [
          {
            "type": "semantic-searchables",
            "id": "9001"
          }
        ]
      }
    },
    "links": {
      "self": "https://{klant}.vragen.ai/api/v1/runs/501"
    }
  },
  "included": [
    {
      "type": "run-sources",
      "id": "91",
      "attributes": {
        "citation_reference": "1",
        "relevance_score": 0.9994,
        "distance_score": null,
        "is_cited": true
      },
      "links": {
        "self": "https://{klant}.vragen.ai/api/v1/run-sources/91"
      }
    },
    {
      "type": "semantic-searchables",
      "id": "9001",
      "attributes": {
        "url": "https://www.voorbeeldgemeente.nl/gemeentehuis",
        "summary": "Het gemeentehuis is geopend van maandag tot en met vrijdag van 09:00 tot 17:00 uur.",
        "title": "Openingstijden gemeentehuis",
        "relevance_score": 0.9994,
        "distance": 0
      },
      "links": {
        "self": "https://{klant}.vragen.ai/api/v1/semantic-searchables/9001"
      }
    }
  ]
}

In dit voorbeeld:

  • sources laat zien welke bronrelaties aan de run gekoppeld zijn

  • searchables bevat de documenten of documentfragmenten die voor het antwoord zijn gebruikt

  • citedSearchables bevat de documenten of documentfragmenten die daadwerkelijk in het antwoord zijn geciteerd

  • citation_reference koppelt de bronrelatie aan de referentie in het antwoord, zoals [1]

Threads ophalen met runs inbegrepen

Gebruik include=runs als je threads wilt ontvangen met de bijbehorende runs in de included sectie van de JSON:API response.

Voorbeeld:

GET https://{klant}.vragen.ai/api/v1/threads?include=runs

Wil je een specifieke thread op UUID ophalen inclusief runs, dan kun je filteren op uuid:

GET https://{klant}.vragen.ai/api/v1/threads?filter[uuid]=5d8f2d34-6a7a-4e41-8c4b-b4f4c2d8d913&include=runs

Algemene request-parameters

De volgende queryparameters zijn beschikbaar voor zowel threads als runs:

include

Type: string
Optioneel

Hiermee kun je gerelateerde resources opnemen in de response.

Voorbeelden:

  • include=runs bij threads

  • include=thread bij runs

sort

Type: string
Optioneel

Sorteervelden worden komma-gescheiden opgegeven. Gebruik:

  • veldnaam voor oplopende sortering

  • -veldnaam voor aflopende sortering

  • +veldnaam expliciet voor oplopende sortering

Voorbeelden:

  • ?sort=-created_at

  • ?sort=created_at

page[offset]

Type: integer
Optioneel
Standaard: 0

Het aantal resultaten dat moet worden overgeslagen.

page[limit]

Type: integer
Optioneel
Standaard: 10

Het maximale aantal resultaten dat moet worden teruggegeven.

Voorbeeld:

?page[offset]=0&page[limit]=25

fields[...]

Type: sparse fieldset
Optioneel

Hiermee kun je het aantal responsevelden beperken.

Voor threads:

fields[threads]=uuid,initiator_type,initiator_origin,user_name,runs_count,completion_time_ms_total,owner_labels,created_at

Voor runs:

fields[runs]=uuid,run_index,status,system_type,question,answer,owner_type,owner_name,feedback,created_at

Als je include=runs gebruikt, kun je beide combineren:

fields[threads]=uuid,runs_count,created_at&fields[runs]=uuid,question,answer,status,created_at

Filters voor threads

Op het threads-endpoint kun je filteren met losse filtervelden.

Beschikbare filters:

  • filter[id]

  • filter[uuid]

  • filter[created_from]

  • filter[created_until]

  • filter[initiator_type]

  • filter[system_type]

Betekenis van threadfilters

filter[uuid]

Zoekt een thread op UUID.

Voorbeeld:

?filter[uuid]=5d8f2d34-6a7a-4e41-8c4b-b4f4c2d8d913

filter[created_from] en filter[created_until]

Beperken threads op aanmaakdatum. De datum wordt toegepast op de created_at van de thread.

Voorbeeld:

?filter[created_from]=2026-05-01&filter[created_until]=2026-05-31

filter[initiator_type]

Filtert op het type initiator van de thread, bijvoorbeeld een gebruiker, bezoeker of systeem.

Voorbeeld:

?filter[initiator_type]=user

filter[system_type]

Geeft alleen threads terug die minimaal een run bevatten met het opgegeven system_type.

Voorbeeld:

?filter[system_type]=answerSystem

Filters voor runs

Op het runs-endpoint kun je filteren met losse filtervelden.

Beschikbare filters:

  • filter[id]

  • filter[uuid]

  • filter[thread_id]

  • filter[thread_uuid]

  • filter[created_from]

  • filter[created_until]

  • filter[tag_ids]

  • filter[feedback]

  • filter[flagged]

  • filter[user_ids]

  • filter[agent_ids]

  • filter[system_ids]

  • filter[system_type]

Betekenis van runfilters

filter[thread_uuid]

Geeft alleen runs terug die horen bij een thread met de opgegeven UUID.

Voorbeeld:

?filter[thread_uuid]=5d8f2d34-6a7a-4e41-8c4b-b4f4c2d8d913

filter[created_from] en filter[created_until]

Beperken runs op aanmaakdatum. De datum wordt toegepast op de created_at van de run.

Voorbeeld:

?filter[created_from]=2026-05-01&filter[created_until]=2026-05-31

filter[tag_ids]

Geeft alleen runs terug die een annotatie hebben met een of meer opgegeven tag-ID's.

Voorbeeld:

?filter[tag_ids][]=12&filter[tag_ids][]=19

filter[feedback]

Filtert runs op thumbs-feedback.

Ondersteunde waarden:

  • positive

  • negative

Voorbeeld:

?filter[feedback]=negative

filter[flagged]

Filtert op moderatie-status.

Ondersteunde waarden:

  • true of weglaten van waarde voor alleen gemodereerde runs

  • false voor alleen niet-gemodereerde runs

  • all voor zowel gemodereerde als niet-gemodereerde runs

Voorbeelden:

  • ?filter[flagged]=true

  • ?filter[flagged]=false

  • ?filter[flagged]=all

filter[user_ids]

Geeft alleen runs terug van threads die gekoppeld zijn aan een of meer gebruikers.

Voorbeeld:

?filter[user_ids][]=3&filter[user_ids][]=8

filter[agent_ids]

Geeft alleen runs terug die door een of meer specifieke agents zijn uitgevoerd.

Voorbeeld:

?filter[agent_ids][]=5

filter[system_ids]

Geeft alleen runs terug die horen bij een of meer specifieke systemen.

Voorbeeld:

?filter[system_ids][]=2

filter[system_type]

Geeft alleen runs terug met een bepaald systeemtype.

Voorbeeld:

?filter[system_type]=answerSystem

Sorteerbare velden

Niet ieder veld is sorteerbaar.

Voor threads

Beschikbaar:

  • created_at

Voorbeeld:

?sort=-created_at

Voor runs

Beschikbaar:

  • created_at

  • time_to_first_token_ms

  • completion_time_ms

Voorbeeld:

?sort=-completion_time_ms

Voorbeeld requests

Voorbeeld 1: threads ophalen met runs inbegrepen

Onderstaand voorbeeld haalt de meest recente threads op, inclusief runs, en beperkt de responsevelden.

GET https://{klant}.vragen.ai/api/v1/threads?include=runs&sort=-created_at&page[offset]=0&page[limit]=10&fields[threads]=uuid,initiator_type,user_name,runs_count,created_at&fields[runs]=uuid,run_index,status,question,answer,created_at

Voorbeeld 2: een thread ophalen op UUID inclusief runs

GET https://{klant}.vragen.ai/api/v1/threads?filter[uuid]=5d8f2d34-6a7a-4e41-8c4b-b4f4c2d8d913&include=runs

Voorbeeld 3: alleen runs ophalen binnen een thread

GET https://{klant}.vragen.ai/api/v1/runs?filter[thread_uuid]=5d8f2d34-6a7a-4e41-8c4b-b4f4c2d8d913&sort=created_at

Voorbeeld 4: runs ophalen met meerdere filters

Onderstaand voorbeeld haalt runs op:

  • uit mei 2026

  • van systeemtype answerSystem

  • met negatieve feedback

  • die niet door een moderator zijn gemarkeerd

GET https://{klant}.vragen.ai/api/v1/runs?filter[created_from]=2026-05-01&filter[created_until]=2026-05-31&filter[system_type]=answerSystem&filter[feedback]=negative&filter[flagged]=false&sort=-created_at&page[offset]=0&page[limit]=25

Voorbeeld response voor threads met runs

Wanneer je include=runs gebruikt, krijg je een JSON:API-collectie met threads in data en de bijbehorende runs in included.

{
  "meta": {
    "total": 1,
    "limit": 10,
    "offset": 0
  },
  "jsonapi": {
    "version": "1.0"
  },
  "links": {
    "self": "https://{klant}.vragen.ai/api/v1/threads?include=runs"
  },
  "data": [
    {
      "type": "threads",
      "id": "3",
      "attributes": {
        "uuid": "5d8f2d34-6a7a-4e41-8c4b-b4f4c2d8d913",
        "initiator_type": "user",
        "initiator_origin": "web",
        "user_name": null,
        "runs_count": 2,
        "completion_time_ms_total": 1834,
        "owner_labels": [
          "Antwoordmodule productie"
        ],
        "created_at": "2026-05-15T12:00:00.000000Z",
        "updated_at": "2026-05-15T12:01:10.000000Z"
      },
      "relationships": {
        "runs": {
          "data": [
            {
              "type": "runs",
              "id": "501"
            },
            {
              "type": "runs",
              "id": "502"
            }
          ]
        }
      },
      "links": {
        "self": "https://{klant}.vragen.ai/api/v1/threads/3"
      }
    }
  ],
  "included": [
    {
      "type": "runs",
      "id": "501",
      "attributes": {
        "uuid": "b8cbbf3b-907d-4f4d-b8f9-cc7b3a7a6771",
        "run_index": 1,
        "status": "finished",
        "failure_reason": null,
        "system_type": "answerSystem",
        "question": "Wat zijn de openingstijden van het gemeentehuis?",
        "answer": "Het gemeentehuis is geopend van maandag tot en met vrijdag van 09:00 tot 17:00 uur [1].",
        "flagged_by_moderator": false,
        "owner_type": "system",
        "owner_name": "Antwoordmodule",
        "owner_version_tag": "prod",
        "time_to_first_token_ms": 242,
        "completion_time_ms": 911,
        "metrics": {
          "ares_faithfulness": 98,
          "ares_answer_relevance": 96,
          "ares_context_relevance": 93
        },
        "feedback": null,
        "feedback_labels": [],
        "search_context": null,
        "created_at": "2026-05-15T12:00:05.000000Z",
        "updated_at": "2026-05-15T12:00:21.000000Z"
      },
      "links": {
        "self": "https://{klant}.vragen.ai/api/v1/runs/501"
      }
    }
  ]
}

Betekenis van responsevelden

Threadvelden

runs_count

Het aantal runs dat voor deze thread zichtbaar is via de JSON:API.

completion_time_ms_total

De totale verwerkingstijd van de zichtbare runs binnen deze thread, uitgedrukt in milliseconden.

owner_labels

Een lijst met unieke labels van de systemen of agents die binnen de thread runs hebben uitgevoerd.

Runvelden

run_index

De volgorde van de run binnen de thread.

question

De gebruikersvraag van de run.

answer

Het antwoord dat op deze run is teruggegeven.

owner_type

Geeft aan of de run door een system of agent is uitgevoerd.

owner_name

De naam van het systeem of de agent die eigenaar is van de run.

feedback

De thumbs-feedback op de run, voor zover aanwezig.

feedback_labels

Een genormaliseerde lijst met feedbacklabels die uit de feedback is afgeleid.

flagged_by_moderator

Geeft aan of de run door een moderator is gemarkeerd.

failure_reason

De foutreden van de run, voor zover aanwezig. Bij succesvolle runs is deze waarde null.

searchables en citedSearchables

Via deze relaties kun je de documenten of documentfragmenten ophalen die voor de run zijn gebruikt, of daadwerkelijk in het antwoord zijn geciteerd.

Praktische aandachtspunten

  • Gebruik threads?include=runs wanneer je complete conversaties wilt tonen.

  • Gebruik runs wanneer je vooral analyse wilt doen op individueel vraagniveau.

  • Gebruik include=searchables of include=citedSearchables op runs wanneer je ook de gebruikte documenten of documentfragmenten wilt analyseren.

  • Als je met UUID's werkt, gebruik dan filter[uuid] of filter[thread_uuid]. De {id} in het pad is de interne JSON:API resource-ID.

  • Voor filters met meerdere waarden, zoals tag_ids, user_ids, agent_ids en system_ids, gebruik je array-syntaxis zoals filter[tag_ids][]=12.

  • De endpoints geven alleen runs terug die zichtbaar zijn binnen de inbox-JSON:API.

  • Zonder include bevat een resource standaard alleen attributes en links; relationships en included verschijnen alleen als je die expliciet opvraagt.

  • Runs zonder timingdata kunnen gewoon in dezelfde response voorkomen; bij sortering op timingvelden vallen deze records automatisch achter resultaten met een geldige timingwaarde.

  • Niet ieder zichtbaar responseveld is automatisch sorteerbaar.

Support

Kom je er niet uit? Mail ons supportteam via service@vragen.ai.

Niet gevonden wat je zocht?

Stel je vraag direct aan vragen.ai.

Wat is vragen.ai precies?

Voorbeeldantwoord door vragen.ai

vragen.ai laat bezoekers hun vraag stellen op je website en geeft direct een betrouwbaar antwoord uit je eigen content, met de bron erbij. Je bepaalt zelf welke bronnen de AI gebruikt.

Bron: Hoe het werkt

Dit is een voorbeeld. De interactieve widget kon hier niet laden, bijvoorbeeld door een scriptblokker of trage verbinding.

Demo aanmaken Probeer het zelf

Je stelt je vraag aan een AI-assistent van vragen.ai. Antwoorden komen uit onze eigen content, met de bron erbij. Waarom we dit melden