Get active Refine with AI session

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usefini.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get active Refine with AI session

> Get the active Refine with AI session and iteration history for one Fini response.

Returns the active Refine with AI session for one Fini response, including every iteration, generated recommendation, and answer replay. Returns JSON `null` when the response has no active session.

Use this route when your UI or automation is anchored to a specific conversation response and needs the current active review, regardless of which iteration was most recently queued.

## Headers

<ParamField header="Authorization" type="string" required>
  Bearer token containing your Fini workspace API key. Format: `Bearer fini_...` The key needs `read` scope.
</ParamField>

## Path parameters

<ParamField path="id" type="string" required>
  Conversation ID containing the reviewed response.
</ParamField>

<ParamField path="eventId" type="string" required>
  ID of the Fini response targeted by the review session. The event must belong to the conversation and have a linked user event.
</ParamField>

## Request example

<RequestExample>
  ~~~bash cURL theme={null}
  curl --request GET \
    --url 'https://api-prod.usefini.com/v2/fix-review/interactions/0b8626b0-4cc8-4a3d-8fc2-f18ad1a4a1a8/events/f61a9a11-2c3b-4704-8f57-7078854d87cf/session/public' \
    --header 'Authorization: Bearer fini_your_api_key'
  ~~~

  ~~~python Python theme={null}
  import requests

  interaction_id = "0b8626b0-4cc8-4a3d-8fc2-f18ad1a4a1a8"
  event_id = "f61a9a11-2c3b-4704-8f57-7078854d87cf"
  response = requests.get(
      f"https://api-prod.usefini.com/v2/fix-review/interactions/{interaction_id}/events/{event_id}/session/public",
      headers={"Authorization": "Bearer fini_your_api_key"},
  )
  session = response.json()
  ~~~

  ~~~javascript Node.js theme={null}
  const interactionId = "0b8626b0-4cc8-4a3d-8fc2-f18ad1a4a1a8";
  const eventId = "f61a9a11-2c3b-4704-8f57-7078854d87cf";

  const response = await fetch(
    `https://api-prod.usefini.com/v2/fix-review/interactions/${interactionId}/events/${eventId}/session/public`,
    { headers: { Authorization: "Bearer fini_your_api_key" } }
  );
  const session = await response.json();
  ~~~
</RequestExample>

## Response

Returns a `FixReviewSession` object or JSON `null`. `iterations` is ordered by `iterationNumber` descending, and `latestIteration` duplicates its first item for convenient polling.

<ResponseExample>
  ~~~json 200 OK theme={null}
  {
    "id": "a5221094-72d4-4b9c-8d30-2f785b108bd9",
    "botId": "2a1cf0f0-f35d-46ad-8e61-a15c86b2b312",
    "status": "resolved",
    "source": "widget",
    "user": {
      "name": "Sam Lee",
      "email": "customer@example.com"
    },
    "messages": [
      {
        "role": "user",
        "content": "How do refunds work?",
        "createdAt": "2026-07-28T08:55:32.000Z"
      },
      {
        "role": "assistant",
        "content": "Refunds are available within 30 days.",
        "createdAt": "2026-07-28T08:55:40.000Z"
      }
    ],
    "createdAt": "2026-07-28T08:55:32.000Z",
    "updatedAt": "2026-07-28T09:10:18.000Z"
  }
  ~~~
</ResponseExample>

## Using the result

Poll this endpoint until `latestIteration.status` reaches a terminal state:

* `ready`: review the replayed answer and proposed changes.
* `no_change`: Fini completed the analysis but did not find an actionable prompt, knowledge, or rule fix.
* `failed`: inspect `latestIteration.error` before retrying or escalating.

For a `ready` iteration:

* Compare `latestIteration.oldAnswerSnapshot.content` with `latestIteration.newAnswerSnapshot.content` to see whether the replay improved the answer.
* Use `latestIteration.replayInteractionId` and `latestIteration.replayEventId` to open or fetch the replayed conversation and answer.
* Inspect `latestIteration.changes`. Each change includes `changeType`, a draft ID when Fini created one, and `rootCause` with the diagnosed failure mode and target details.

The session response does not apply the fix. A prompt, knowledge, or rule recommendation becomes live only after the corresponding draft is reviewed and published.

## FixReviewSession object

<AccordionGroup>
  <Accordion title="FixReviewSession" icon="comments">
    | Field | Type | Description |
    | - | - | - |
    | `id` | string | Fix-review session ID. |
    | `companyId` | string | Workspace ID. |
    | `interactionId` | string | Reviewed conversation ID. |
    | `targetEventId` | string | Original Fini response under review. |
    | `targetUserEventId` | string \| null | Linked user event used to replay the response. |
    | `status` | string | `active`, `published`, or `closed`. This route only returns an `active` session. |
    | `publishedIterationId` | string \| null | Iteration applied from this session, when present. |
    | `publishedAt` | string \| null | ISO 8601 publication timestamp. |
    | `closedAt` | string \| null | ISO 8601 close timestamp. |
    | `closedReason` | string \| null | Reason the session was closed. |
    | `createdAt` | string | ISO 8601 creation timestamp. |
    | `updatedAt` | string | ISO 8601 last-update timestamp. |
    | `originalAnswerSnapshot` | `AnswerSnapshot` \| null | Snapshot of the original response. |
    | `latestIteration` | `FixIteration` \| null | Most recent iteration. |
    | `iterations` | `FixIteration[]` | All iterations, newest first. |
  </Accordion>

  <Accordion title="FixIteration" icon="rotate">
    | Field | Type | Description |
    | - | - | - |
    | `id` | string | Iteration ID. |
    | `companyId` | string | Workspace ID. |
    | `sessionId` | string | Parent session ID. |
    | `interactionId` | string | Reviewed conversation ID. |
    | `targetEventId` | string | Original Fini response under review. |
    | `previousIterationId` | string \| null | Previous iteration in the session. |
    | `backgroundJobId` | string \| null | Processing job ID. |
    | `replayInteractionId` | string \| null | Conversation created for the replay. |
    | `replayEventId` | string \| null | Generated answer event from the replay. |
    | `iterationNumber` | number | One-based revision number within the session. |
    | `status` | string | `queued`, `generating_changes`, `replaying`, `ready`, `no_change`, `failed`, `published`, or `superseded`. |
    | `feedbackNote` | string | Feedback supplied when the iteration was created. |
    | `summary` | string \| null | Generated summary of the recommendation. |
    | `confidence` | string \| null | `high`, `medium`, `low`, or `null`. |
    | `error` | string \| null | Processing error for a failed iteration. |
    | `publishedAt` | string \| null | ISO 8601 publication timestamp. |
    | `startedAt` | string \| null | ISO 8601 processing-start timestamp. |
    | `completedAt` | string \| null | ISO 8601 completion timestamp. |
    | `createdAt` | string | ISO 8601 creation timestamp. |
    | `updatedAt` | string | ISO 8601 last-update timestamp. |
    | `oldAnswerSnapshot` | `AnswerSnapshot` \| null | Answer used as the baseline for this iteration. |
    | `newAnswerSnapshot` | `AnswerSnapshot` \| null | Answer generated by the replay. |
    | `changes` | `FixChange[]` | Suggested prompt, knowledge, or rule changes. |
  </Accordion>

  <Accordion title="AnswerSnapshot" icon="message">
    | Field | Type | Description |
    | - | - | - |
    | `interactionId` | string | Conversation containing the answer. |
    | `eventId` | string | Answer event ID. |
    | `originalEventId` | string \| null | Optional original event referenced by a replay event, when available. |
    | `content` | string \| null | Answer content. |
    | `role` | string | Event role. The reviewed answer is normally `finibot`. |
    | `type` | string | Event type. |
    | `createdAt` | string | ISO 8601 event timestamp. |
  </Accordion>

  <Accordion title="FixChange" icon="wand-magic-sparkles">
    | Field | Type | Description |
    | - | - | - |
    | `id` | string | Change ID. |
    | `companyId` | string | Workspace ID. |
    | `sessionId` | string | Parent session ID. |
    | `iterationId` | string | Parent iteration ID. |
    | `interactionId` | string | Reviewed conversation ID. |
    | `targetEventId` | string | Reviewed Fini response ID. |
    | `rootCause` | object | Diagnosed failure and target details. See [Root cause object](#root-cause-object). |
    | `changeType` | string | `update_prompt`, `update_rule`, `create_article`, or `update_article`. |
    | `draftPromptVersionId` | string \| null | Draft prompt version created for a prompt recommendation. |
    | `draftArticleId` | string \| null | Draft article created for a knowledge recommendation. |
    | `draftRuleVersionId` | string \| null | Draft rule version created for a rule recommendation. |
    | `createdAt` | string | ISO 8601 creation timestamp. |
  </Accordion>
</AccordionGroup>

### Root cause object

`rootCause` includes the failure classification and the target Fini should change:

* `failureStage`, such as `planning`, `knowledge_search`, `knowledge_content`, `rule_execution`, `instruction_resolution`, or `answer_generation`.
* `failureMode`, such as `required_search_skipped`, `incorrect_knowledge`, or `required_information_omitted`.
* `reasoning`, explaining why Fini selected this failure.
* `target.kind`, which is `prompt`, `kb_article`, or `rule`.
* `target.operation`, which is `create` or `update` when the target supports both.
* Target-specific identifiers and fields, such as prompt section IDs, knowledge article IDs, editable knowledge fields, or rule IDs.

Use the draft ID on the `FixChange` record to inspect the generated artifact in the relevant Fini surface. Use `rootCause` to explain why that artifact was proposed.

### Fix-change enum values

`changeType` can be:

* `update_prompt`
* `update_rule`
* `create_article`
* `update_article`

`failureMode` depends on `failureStage`. Common values include `required_search_skipped`, `relevant_knowledge_not_available`, `incorrect_knowledge`, `required_rule_behavior_missing`, `required_instruction_omitted`, and `required_information_omitted`.

## Errors

<AccordionGroup>
  <Accordion title="400 Bad Request" icon="circle-exclamation">
    The event does not belong to the conversation, is not Fini-authored, or has no linked user event for replay.
  </Accordion>

  <Accordion title="401 Unauthorized" icon="lock">
    The API key is missing, malformed, revoked, or invalid.
  </Accordion>

  <Accordion title="403 Forbidden" icon="shield-halved">
    The API key does not include the `read` scope required for this route.
  </Accordion>

  <Accordion title="404 Not Found" icon="ghost">
    The conversation or target event does not exist in the workspace.
  </Accordion>

  <Accordion title="500 Internal Server Error" icon="triangle-exclamation">
    Fini could not load the Refine with AI session or its related records.
  </Accordion>
</AccordionGroup>


## Related topics

- [Get Refine with AI session](/en/api-reference/get-fix-review-session.md)
- [Create Refine with AI iteration](/en/api-reference/create-fix-review-iteration.md)
- [Overview](/en/api-reference/refine-with-ai.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.