Get event metadata

> ## 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 event metadata

> Fetch reasoning, knowledge, tag, attribute, and rule metadata for one Fini-authored event.

Returns execution metadata for one Fini-authored event in your workspace. Use this endpoint when a conversation export tells you which event to inspect, but you need the detailed trace behind that response: planning, knowledge search, answer reasoning, tag selection, executed Attributes, and executed Rules.

<Tip>
  Use [List conversations](/en/api-reference/list-conversations) or [Get conversation](/en/api-reference/get-conversation) to discover event IDs. This route only returns metadata for events where `role` is `finibot`.
</Tip>

<Note>
  This public API route is currently registered as `/v2/hc-events/{id}/metadata`, without the `/public` suffix used by most other public endpoints. It still requires a workspace API key with `read` scope.
</Note>

## 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>
  Event ID to inspect. The event must belong to your workspace and have `role: "finibot"`.
</ParamField>

<RequestExample>
  ~~~bash cURL theme={null}
  curl --request GET \
    --url 'https://api-prod.usefini.com/v2/hc-events/2f7dcb2f-2a41-4f5d-a4ad-2b6cbf61d20a/metadata' \
    --header 'Authorization: Bearer fini_your_api_key'
  ~~~

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

  event_id = "2f7dcb2f-2a41-4f5d-a4ad-2b6cbf61d20a"
  response = requests.get(
      f"https://api-prod.usefini.com/v2/hc-events/{event_id}/metadata",
      headers={"Authorization": "Bearer fini_your_api_key"},
  )
  metadata = response.json()
  ~~~

  ~~~javascript Node.js theme={null}
  const eventId = "2f7dcb2f-2a41-4f5d-a4ad-2b6cbf61d20a";

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

## Response

<ResponseField name="planning" type="object | null">
  Planning trace for the response, including reasoning and whether Fini decided to run knowledge search.
</ResponseField>

<ResponseField name="knowledgeSearch" type="object | null">
  Knowledge-search trace, including top-result reasoning, selection reasoning, and the articles considered for the response.
</ResponseField>

<ResponseField name="relevantMemories" type="array | null">
  Conversation memory summaries selected for the response. Each item includes `id`, `summary`, and `conversationEndedAt`.
</ResponseField>

<ResponseField name="generateAnswer" type="object | null">
  Answer-generation reasoning items returned by the model trace.
</ResponseField>

<ResponseField name="inputTagSelection" type="object | null">
  Input tag-selection reasoning and chosen tags, when input tags were selected for the event.
</ResponseField>

<ResponseField name="outputTagSelection" type="object | null">
  Output tag-selection reasoning and chosen tags, when output tags were selected for the event.
</ResponseField>

<ResponseField name="executedUserAttributes" type="array | null">
  Attribute executions exposed for this event, including tool names, success state, extracted data, and external API step results when available.
</ResponseField>

<ResponseField name="executedRules" type="object | null">
  Rule execution details for the selected rule, including `ruleId`, `ruleName`, and node execution results when available.
</ResponseField>

<ResponseExample>
  ~~~json 200 OK theme={null}
  {
    "planning": {
      "reasoning": "The customer is asking about refund eligibility, so knowledge search is needed.",
      "performKnowledgeSearch": true
    },
    "knowledgeSearch": {
      "topOneReasoning": "The refund policy article directly answers the question.",
      "selectionReasoning": "Selected the most recent public refund policy article.",
      "articles": [
        {
          "id": "7f1a8c7e-20db-4511-9b7b-95d894f9d1b2",
          "title": "Refund policy",
          "version": 3
        }
      ]
    },
    "relevantMemories": [
      {
        "id": "6c6ec2c1-23cb-4502-8b03-0f6eb8faef26",
        "summary": "The customer previously asked about a delayed refund for order R-1042.",
        "conversationEndedAt": "2026-07-25T14:18:00.000Z"
      }
    ],
    "generateAnswer": {
      "reasoning": [
        {
          "name": "Policy grounding",
          "reasoning": "Use the 30-day refund window and avoid promising exceptions."
        }
      ]
    },
    "inputTagSelection": null,
    "outputTagSelection": {
      "reasoning": "The response resolves a policy question.",
      "chosenTags": {
        "Conversation Status": ["Resolved"],
        "Topic": ["Refunds"]
      }
    },
    "executedUserAttributes": [
      {
        "id": "9c4b8e11-f4f5-4ef4-a82f-34bb080da8c6",
        "name": "Get order status",
        "success": true,
        "extractedData": {
          "orderStatus": "delivered"
        },
        "results": [
          {
            "id": "2d2a7f0e-8b3a-4f7f-9b4b-3b2e4a7a3c23",
            "name": "Fetch order",
            "success": true,
            "data": {
              "status": "delivered"
            }
          }
        ]
      }
    ],
    "executedRules": {
      "ruleId": "e071d8b6-a780-49fa-a3ac-01f7312b20ef",
      "ruleName": "Refund policy routing",
      "results": [
        {
          "id": "3a70c315-0fe0-42b8-a0c2-ec2ad0fda69d",
          "name": "Check refund window",
          "type": "CONDITION",
          "success": true,
          "result": {
            "eligible": true
          }
        }
      ]
    }
  }
  ~~~
</ResponseExample>

## Errors

<AccordionGroup>
  <Accordion title="400 Bad Request" icon="circle-exclamation">
    The event ID is missing, or the event is not from the Fini bot. Only `finibot` events have this metadata response.
  </Accordion>

  <Accordion title="401 Unauthorized" icon="lock">
    The API key is missing, malformed, revoked, or invalid. Confirm you are sending `Authorization: Bearer fini_...` with the full key.
  </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="magnifying-glass">
    The event does not exist or does not belong to the workspace tied to your API key.
  </Accordion>
</AccordionGroup>


## Related topics

- [Overview](/en/api-reference/conversations.md)
- [Get replay events](/en/api-reference/get-replay-events.md)
- [API overview](/en/api-reference/overview.md)


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