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'
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()
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();
{
"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
}
}
]
}
}
Conversations
Get event metadata
Fetch reasoning, knowledge, tag, attribute, and rule metadata for one Fini-authored event.
GET
/
v2
/
hc-events
/
{id}
/
metadata
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'
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()
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();
{
"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
}
}
]
}
}
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.
Use List conversations or Get conversation to discover event IDs. This route only returns metadata for events where
role is finibot.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.Headers
string
required
Bearer token containing your Fini workspace API key. Format:
Bearer fini_... The key needs read scope.Path parameters
string
required
Event ID to inspect. The event must belong to your workspace and have
role: "finibot".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'
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()
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();
Response
object | null
Planning trace for the response, including reasoning and whether Fini decided to run knowledge search.
object | null
Knowledge-search trace, including top-result reasoning, selection reasoning, and the articles considered for the response.
array | null
Conversation memory summaries selected for the response. Each item includes
id, summary, and conversationEndedAt.object | null
Answer-generation reasoning items returned by the model trace.
object | null
Input tag-selection reasoning and chosen tags, when input tags were selected for the event.
object | null
Output tag-selection reasoning and chosen tags, when output tags were selected for the event.
array | null
Attribute executions exposed for this event, including tool names, success state, extracted data, and external API step results when available.
object | null
Rule execution details for the selected rule, including
ruleId, ruleName, and node execution results when available.{
"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
}
}
]
}
}
Errors
400 Bad Request
400 Bad Request
The event ID is missing, or the event is not from the Fini bot. Only
finibot events have this metadata response.401 Unauthorized
401 Unauthorized
The API key is missing, malformed, revoked, or invalid. Confirm you are sending
Authorization: Bearer fini_... with the full key.403 Forbidden
403 Forbidden
The API key does not include the
read scope required for this route.404 Not Found
404 Not Found
The event does not exist or does not belong to the workspace tied to your API key.
Was this page helpful?

