Evaluation & Export

This page documents two small, narrow parts of the API: post-session Evaluation (an automatically generated score/summary for a completed conversation) and asynchronous document export (a background job that renders and stores a downloadable file). Both follow a request-then-poll pattern rather than returning a result synchronously.

All operations on this page except requestStudyKitExport require a valid JWT (Authorization: Bearer <token>) — see Authentication. requestStudyKitExport uses SDK/session auth instead (see below).

Every request in this reference must include the x-huat-platform: customer header in addition to standard GraphQL headers, unless noted otherwise.

The EvaluationDto type

Field	Type	Notes
id	Int!
sessionId	Int!
score	Int!
summary	String!
strengths	[String!]!
weaknesses	[String!]!
recommendation	String!
transcript	JSON!	The full conversation transcript this evaluation was generated from.
generatedAt	DateTime	When the background job finished generating this evaluation. null until it completes.
createdAt	DateTime!
updatedAt	DateTime!

The ExportRecordDto type

Field	Type	Notes
id	Int!
kind	ExportKind!	Currently only STUDY_KIT.
status	ExportStatus!	PENDING | RENDERING | READY | FAILED | FALLBACK_READY.
downloadUrl	String	Populated when status is READY or FALLBACK_READY. Both are fresh presigned URLs issued on every exportRecord call, never persisted — READY uses a 24h expiry, FALLBACK_READY uses a 7-day expiry (the fixed fallback document is polled less predictably than a fresh render).
errorMessage	String	Populated when status is FAILED or FALLBACK_READY — the underlying render error, even when a fallback download is offered instead.
fileSizeBytes	Int
createdAt	DateTime!
updatedAt	DateTime!

enum ExportKind {
  STUDY_KIT
}

enum ExportStatus {
  PENDING
  RENDERING
  READY
  FAILED
  FALLBACK_READY
}

FALLBACK_READY means the live render failed, but a pre-generated “ready to download” document is available as a substitute — treat it the same as READY for the purpose of showing a download link, but note via errorMessage (also populated) that this isn’t the freshly-rendered result. Not every environment has a fallback configured; a render failure with no fallback available still surfaces as plain FAILED.

---

Queries

evaluation

Fetches the async Evaluation (sentiment/outcome/score) for a Session, scoped to the caller’s tenant. Returns null until the Session has ended AND the background evaluation job has completed — this is generated asynchronously after endSession is called, so querying immediately after ending a session will very likely return null. Poll this query (or wait a few seconds and refetch) rather than expecting a result immediately.

Auth: JWT

evaluation(sessionId: Int!): EvaluationDto

Request

query GetEvaluation($sessionId: Int!) {
  evaluation(sessionId: $sessionId) {
    id
    score
    summary
    strengths
    weaknesses
    recommendation
    generatedAt
  }
}

{ "sessionId": 314 }

POST /graphql
Content-Type: application/json
Authorization: Bearer <jwt>
x-huat-platform: customer

Response — job not finished yet

{ "data": { "evaluation": null } }

Response — job finished

{
  "data": {
    "evaluation": {
      "id": 88,
      "score": 82,
      "summary": "The caller resolved their billing question with minimal back-and-forth.",
      "strengths": [
        "Clear, concise answers",
        "Correctly identified the billing issue on the first try"
      ],
      "weaknesses": ["Did not confirm the resolution before ending the call"],
      "recommendation": "Add a closing confirmation step to the workflow.",
      "generatedAt": "2026-08-09T10:02:15.000Z"
    }
  }
}

exportRecord

Polls the status of a previously requested export (see requestStudyKitExport below). Returns a fresh presigned downloadUrl (24h expiry) once status is READY — the URL is never persisted, so its expiry always counts from this call, not from when rendering finished. Call this repeatedly (e.g. every few seconds) until status reaches a terminal state (READY, FALLBACK_READY, or FAILED). When called with a session-scoped avatarToken rather than a JWT, id must belong to the session that token was minted for — a mismatched id returns not-found rather than another session’s record.

Auth: JWT

exportRecord(id: Int!): ExportRecordDto!

Request

query GetExportRecord($id: Int!) {
  exportRecord(id: $id) {
    id
    kind
    status
    downloadUrl
    errorMessage
    fileSizeBytes
  }
}

{ "id": 21 }

Response — still rendering

{
  "data": {
    "exportRecord": {
      "id": 21,
      "kind": "STUDY_KIT",
      "status": "RENDERING",
      "downloadUrl": null,
      "errorMessage": null,
      "fileSizeBytes": null
    }
  }
}

Response — ready

{
  "data": {
    "exportRecord": {
      "id": 21,
      "kind": "STUDY_KIT",
      "status": "READY",
      "downloadUrl": "https://storage.example.com/exports/tenant-9/21.pdf?X-Signature=...",
      "errorMessage": null,
      "fileSizeBytes": 512044
    }
  }
}

---

Mutations

requestStudyKitExport

Starts an asynchronous document export job. Returns immediately with status: PENDING; poll exportRecord(id) until status reaches READY (downloadUrl populated), FALLBACK_READY (downloadUrl populated with a fixed substitute document, errorMessage also populated), or FAILED (errorMessage populated, no download available). The rendered document is a pre-authored, structured document assembled server-side from a fixed template, not generated fresh by an LLM on every call — repeated requests for the same underlying content produce the same document.

Auth: Session-scoped SDK token (the avatarToken returned by sdkStart — see Sessions), not a JWT. This mutation is designed to be triggered from within an active embedded session, not a standalone authenticated API caller. As of 2026-09-08, when sessionId is supplied it must match the session the presented avatarToken was minted for — see Sessions: avatarToken binding.

requestStudyKitExport(sessionId: Int): ExportRecordDto!

Arguments

Argument	Type	Required	Notes
sessionId	Int	no	Associates the export with a session context, when called from within one.

Request

mutation RequestStudyKitExport($sessionId: Int) {
  requestStudyKitExport(sessionId: $sessionId) {
    id
    kind
    status
  }
}

{ "sessionId": 314 }

POST /graphql
Content-Type: application/json
Authorization: Bearer <avatar-token>
x-huat-platform: customer

Response

{
  "data": {
    "requestStudyKitExport": {
      "id": 21,
      "kind": "STUDY_KIT",
      "status": "PENDING"
    }
  }
}

Poll exportRecord(id: 21) afterward to retrieve the downloadUrl once rendering finishes.

---

See also

• Knowledge Base & Embeddings
• Avatar Config
• API Reference: Overview