Manage entity results and exports

Learn more about managing per-entity results and exports for a conversation.

The Manage entity results and exports operations let you review how an LRT job processed each entity, drill into a single entity's full record, and export the results so you can analyze them outside Reltio.

The following operations are supported:

Entity status counts for a conversation

Aggregate processed/failed/needs-review counts for a conversation, with a per-entity-type breakdown. Answer counting questions from this endpoint rather than listing every entity.

Note: The per-entity state table used by this operation is populated only for tenants with Horizontal LRT enabled. For other tenants, the counts are zero.

HTTP method and endpoint

Use the following HTTP method and endpoint path to entity status counts for a conversation.

POST {TenantURL}/ai/agentflow/api/v202605/{tenant_id}/lrt/jobs/conversation/{conversation_id}/entities/summary

The following table describes the endpoint path parameters.


Parameter	Type	Required	Description
`TenantURL`	String	Yes	The base URL for your tenant.
`conversation_id`	String	Yes	-
`tenant_id`	String	Yes	The tenant identifier.

Request headers

The following request headers must be included.


Header	Value	Required
`Authorization`	`<access_token>`	Yes
`Content-Type`	application/json	Yes

Request body

The following table describes the request body parameters.


Parameter	Type	Required	Description	Accepted values / Default
filter_condition	Object	No	Optional entity_type / status filter to scope the counts	-
filter_condition.entity_type	String	No	Filter by entity type	-
filter_condition.entity_id	String	No	Filter by entity ID	-
filter_condition.status	String	No	Filter by entity outcome status	-
filter_condition.decision_code	String	No	Filter by structured decision code (e.g. NO_MATCH)	-
run_id	String	No	Scope the counts to a single worker run	-

Example request

Use the following example to see how a complete request is structured, with headers and a JSON body.

POST {TenantURL}/ai/agentflow/api/v202605/tenant-xyz/lrt/jobs/conversation/example-id/entities/summary
Authorization: <access_token>
Content-Type: application/json

{
  "filter_condition": {
    "entity_type": "<string>",
    "entity_id": "<string>",
    "status": "<string>",
    "decision_code": "<string>"
  },
  "run_id": "<string>"
}

Response body

The following table describes the fields returned in the response body.


Parameter	Type	Description
`conversation_id`	String	Conversation identifier
`total`	Integer	Total entities counted
`counts`	Object	Counts bucketed by public status
`counts.processed`	Integer	Entities that completed successfully
`counts.failed`	Integer	Entities that failed processing
`counts.needs_review`	Integer	Entities awaiting human review
`by_entity_type`	Array	Per-entity-type status breakdown
`by_entity_type[].entity_type`	String	Entity type, or 'unknown' when the producer omitted it
`by_entity_type[].processed`	Integer	Processed entities of this type
`by_entity_type[].failed`	Integer	Failed entities of this type
`by_entity_type[].needs_review`	Integer	Needs-review entities of this type
`by_entity_type[].total`	Integer	Total entities of this type
`top_reasons`	Array	Most common short reasons, ordered by descending count
`top_reasons[].reason`	String	Short rationale text
`top_reasons[].status`	String	Public status the reason was recorded against
`top_reasons[].count`	Integer	Entities sharing this reason
`top_reasons_truncated`	Boolean	True if distinct reasons were dropped by the top-reasons cap
`by_decision_code`	Array	Counts per structured decision code. Lower cardinality and more reliable than grouping free-text reasons
`by_decision_code[].decision_code`	String	Structured outcome code, e.g. NO_MATCH
`by_decision_code[].status`	String	Public status the code was recorded against
`by_decision_code[].count`	Integer	Entities sharing this code
`sample_entities`	Array	A handful of matching entity rows (same shape as entities/list), so a caller can see concrete entity_id/decision_code/reason values before building an entities/list or entities/detail filter
`sample_entities[].entity_id`	String	Entity identifier
`sample_entities[].entity_type`	String	Entity type, reduced from its stored URI to the bare name
`sample_entities[].label`	String	Human-readable entity label
`sample_entities[].status`	String	Normalized status: processed, failed, or needs_review
`sample_entities[].decision_code`	String	Structured outcome code, e.g. NO_MATCH
`sample_entities[].reason`	String	Short rationale, truncated for compactness
`sample_entities[].confidence`	String	Confidence band, when the producer emitted one
`sample_entities[].run_id`	String	Run this entity was processed under
`filtered_total`	Integer	Count for the requested status filter, when one was supplied
`truncated`	Boolean	True if the count sweep hit its page cap, so counts under-report

Example response

The following example shows a response with successful response.

{
  "conversation_id": "<string>",
  "total": 0,
  "counts": {
    "processed": 0,
    "failed": 0,
    "needs_review": 0
  },
  "by_entity_type": [
    {
      "entity_type": "<string>",
      "processed": 0,
      "failed": 0,
      "needs_review": 0,
      "total": 0
    }
  ],
  "top_reasons": [
    {
      "reason": "<string>",
      "status": "<string>",
      "count": 0
    }
  ],
  "top_reasons_truncated": false,
  "by_decision_code": [
    {
      "decision_code": "<string>",
      "status": "<string>",
      "count": 0
    }
  ],
  "sample_entities": [
    {
      "entity_id": "<string>",
      "entity_type": "<string>",
      "label": "<string>",
      "status": "<string>",
      "decision_code": "<string>",
      "reason": "<string>",
      "confidence": "<string>",
      "run_id": "<string>"
    }
  ],
  "filtered_total": 0,
  "truncated": false
}

Error codes and recommended actions

The following table lists the possible error responses returned by this API.


HTTP status	Description	Recommended action
`422 Unprocessable Entity`	Validation Error	Review the request parameters or body, correct the invalid values, and resend the request.

Paginated per-entity results for a conversation

One page of per-entity rows, each with a short reason. Filter by entity type, entity id, or status. Use the summary endpoint for counts and the detail endpoint for a single entity's full record.

HTTP method and endpoint

Use the following HTTP method and endpoint path to paginated per-entity results for a conversation.

POST {TenantURL}/ai/agentflow/api/v202605/{tenant_id}/lrt/jobs/conversation/{conversation_id}/entities/list

The following table describes the endpoint path parameters.


Parameter	Type	Required	Description
`TenantURL`	String	Yes	The base URL for your tenant.
`conversation_id`	String	Yes	-
`tenant_id`	String	Yes	The tenant identifier.

Request headers

The following request headers must be included.


Header	Value	Required
`Authorization`	`<access_token>`	Yes
`Content-Type`	application/json	Yes

Request body

The following table describes the request body parameters.


Parameter	Type	Required	Description	Accepted values / Default
filter_condition	Object	No	Filter condition to apply to the conversation's entities	-
filter_condition.entity_type	String	No	Filter by entity type	-
filter_condition.entity_id	String	No	Filter by entity ID	-
filter_condition.status	String	No	Filter by entity outcome status	-
filter_condition.decision_code	String	No	Filter by structured decision code (e.g. NO_MATCH)	-
run_id	String	No	Scope the list to a single worker run	-
reason_contains	String	No	Case-insensitive substring match against the entity's short reason. Bounded in length because matching is done server-side in Python over the conversation partition.	-
limit	Integer	No	Maximum entities per page	Default: `25`
page_token	String	No	Pagination cursor from a previous response	-

Example request

Use the following example to see how a complete request is structured, with headers and a JSON body.

POST {TenantURL}/ai/agentflow/api/v202605/tenant-xyz/lrt/jobs/conversation/example-id/entities/list
Authorization: <access_token>
Content-Type: application/json

{
  "filter_condition": {
    "entity_type": "<string>",
    "entity_id": "<string>",
    "status": "<string>",
    "decision_code": "<string>"
  },
  "run_id": "<string>",
  "reason_contains": "<string>",
  "limit": 0,
  "page_token": "<string>"
}

Response body

The following table describes the fields returned in the response body.


Parameter	Type	Description
`conversation_id`	String	Conversation identifier
`entities`	Array	Matching entity rows
`entities[].entity_id`	String	Entity identifier
`entities[].entity_type`	String	Entity type, reduced from its stored URI to the bare name
`entities[].label`	String	Human-readable entity label
`entities[].status`	String	Normalized status: processed, failed, or needs_review
`entities[].decision_code`	String	Structured outcome code, e.g. NO_MATCH
`entities[].reason`	String	Short rationale, truncated for compactness
`entities[].confidence`	String	Confidence band, when the producer emitted one
`entities[].run_id`	String	Run this entity was processed under
`search_truncated`	Boolean	True if a reason search stopped at its page cap before filling the page, so further matches may exist beyond this result
`pagination`	Object	Pagination information
`pagination.total_count`	Integer	Total number of items in the current page
`pagination.next_page_token`	String	Opaque cursor for the next page of results. Null if this is the last page.
`pagination.limit`	Integer	Page size used for this response

Example response

The following example shows a response with successful response.

{
  "conversation_id": "<string>",
  "entities": [
    {
      "entity_id": "<string>",
      "entity_type": "<string>",
      "label": "<string>",
      "status": "<string>",
      "decision_code": "<string>",
      "reason": "<string>",
      "confidence": "<string>",
      "run_id": "<string>"
    }
  ],
  "search_truncated": false,
  "pagination": {
    "total_count": 50,
    "next_page_token": "eyJvZmZzZXQiOiA1MH0=",
    "limit": 50
  }
}

Error codes and recommended actions

The following table lists the possible error responses returned by this API.


HTTP status	Description	Recommended action
`422 Unprocessable Entity`	Validation Error	Review the request parameters or body, correct the invalid values, and resend the request.

Full detail for a single entity in a conversation

The complete stored record for one entity, including its longer summary, error text and remaining producer attributes.

HTTP method and endpoint

Use the following HTTP method and endpoint path to full detail for a single entity in a conversation.

POST {TenantURL}/ai/agentflow/api/v202605/{tenant_id}/lrt/jobs/conversation/{conversation_id}/entities/detail

The following table describes the endpoint path parameters.


Parameter	Type	Required	Description
`TenantURL`	String	Yes	The base URL for your tenant.
`conversation_id`	String	Yes	-
`tenant_id`	String	Yes	The tenant identifier.

Request headers

The following request headers must be included.


Header	Value	Required
`Authorization`	`<access_token>`	Yes
`Content-Type`	application/json	Yes

Request body

The following table describes the request body parameters.


Parameter	Type	Required	Description	Accepted values / Default
entity_id	String	Yes	Entity identifier to look up	-

Example request

Use the following example to see how a complete request is structured, with headers and a JSON body.

POST {TenantURL}/ai/agentflow/api/v202605/tenant-xyz/lrt/jobs/conversation/example-id/entities/detail
Authorization: <access_token>
Content-Type: application/json

{
  "entity_id": "<string>"
}

Response body

The following table describes the fields returned in the response body.


Parameter	Type	Description
`conversation_id`	String	Conversation identifier
`entity_id`	String	Entity identifier
`entity_type`	String	Entity type, reduced from its stored URI to the bare name. The full URI is preserved under `attributes`
`label`	String	Human-readable entity label
`status`	String	Normalized status: processed, failed, or needs_review
`decision_code`	String	Structured outcome code, e.g. NO_MATCH
`reason`	String	Short rationale
`summary`	String	Longer per-entity narrative, when stored
`run_summary`	String	The part of the owning run's summary column (lifecycle repository) that concerns this entity, capped at ENTITY_DETAIL_SUMMARY_MAX_CHARS. That column is a batch-level report covering every record the worker processed, so when this entity's row is found only that row plus the table headings are returned - see `run_summary_is_excerpt`. Null when the entity carries no run id or the run could not be read.
`run_summary_is_excerpt`	Boolean	True when `run_summary` is this entity's own slice of the batch report. False means no row mentioned the entity and the value is a generic head of the batch narrative, which may describe other records
`run_summary_truncated`	Boolean	True if the run summary was cut by the character cap
`error`	String	Error text, when the entity failed
`confidence`	String	Confidence band, when the producer emitted one
`action`	String	Action taken (merge, not_match, ...)
`record_type`	String	Record type, when the producer emitted one
`run_id`	String	Run this entity was processed under
`job_id`	String	Job reference
`message_id`	String	Parent message identifier
`task_index`	Integer	Task index within the message
`created_at`	String	ISO-8601 UTC creation timestamp
`updated_at`	String	ISO-8601 UTC update timestamp
`attributes`	Object	Remaining raw producer fields, excluding oversized values

Example response

The following example shows a response with successful response.

{
  "conversation_id": "<string>",
  "entity_id": "<string>",
  "entity_type": "<string>",
  "label": "<string>",
  "status": "<string>",
  "decision_code": "<string>",
  "reason": "<string>",
  "summary": "<string>",
  "run_summary": "<string>",
  "run_summary_is_excerpt": false,
  "run_summary_truncated": false,
  "error": "<string>",
  "confidence": "<string>",
  "action": "<string>",
  "record_type": "<string>",
  "run_id": "<string>",
  "job_id": "<string>",
  "message_id": "<string>",
  "task_index": 0,
  "created_at": "<string>",
  "updated_at": "<string>",
  "attributes": {}
}

Error codes and recommended actions

The following table lists the possible error responses returned by this API.


HTTP status	Description	Recommended action
`404 Not Found`	Entity not found in this conversation	Verify the identifier in the request path and resend the request with a valid identifier.
`422 Unprocessable Entity`	Validation Error	Review the request parameters or body, correct the invalid values, and resend the request.

List entity exports for a conversation job

List exports created by the authenticated user for this conversation.

HTTP method and endpoint

Use the following HTTP method and endpoint path to list entity exports for a conversation job.

GET {TenantURL}/ai/agentflow/api/v202605/{tenant_id}/lrt/jobs/{conversation_id}/entities/export

The following table describes the endpoint path parameters.


Parameter	Type	Required	Description
`TenantURL`	String	Yes	The base URL for your tenant.
`conversation_id`	String	Yes	-
`tenant_id`	String	Yes	The tenant identifier.

Query parameters

The following table describes the query parameters and their values.


Parameter	Type	Required	Description	Accepted values / Default
`limit`	Integer	No	Max results per page	Default: `50`
`page_token`	String	No	Pagination cursor from a previous response	Default: none

Request headers

The following request headers must be included.


Header	Value	Required
`Authorization`	`<access_token>`	Yes

Request body

This operation does not require a request body.

Example request

Use the following example to see how a complete request is structured, with headers.

GET {TenantURL}/ai/agentflow/api/v202605/tenant-xyz/lrt/jobs/example-id/entities/export
Authorization: <access_token>

Response body

The following table describes the fields returned in the response body.


Parameter	Type	Description
`exports`	Array	-
`exports[].export_id`	String	-
`exports[].status`	String	-
`exports[].format`	String	-
`exports[].include_conversation`	Boolean	-
`exports[].filters`	Object	-
`exports[].filters.status`	String	-
`exports[].filters.confidence`	String	-
`exports[].total_count`	Integer	-
`exports[].written_rows`	Integer	-
`exports[].written_bytes`	Integer	-
`exports[].created_at`	String	-
`exports[].completed_at`	String	-
`exports[].expires_at`	String	-
`exports[].filename`	String	-
`exports[].download_url`	String	-
`exports[].email_sent_at`	String	-
`exports[].error_code`	String	-
`next_page_token`	String	Opaque token for the next page; null when the partition is exhausted
`total_count`	Integer	Number of exports in this page

Example response

The following example shows a response with paginated list of exports.

{
  "exports": [
    {
      "export_id": "<string>",
      "status": "<string>",
      "format": "<string>",
      "include_conversation": false,
      "filters": {
        "status": "<string>",
        "confidence": "<string>"
      },
      "total_count": 0,
      "written_rows": 0,
      "written_bytes": 0,
      "created_at": "<string>",
      "completed_at": "<string>",
      "expires_at": "<string>",
      "filename": "<string>",
      "download_url": "<string>",
      "email_sent_at": "<string>",
      "error_code": "<string>"
    }
  ],
  "next_page_token": "<string>",
  "total_count": 0
}

Error codes and recommended actions

The following table lists the possible error responses returned by this API.


HTTP status	Description	Recommended action
`404 Not Found`	Job not found	Verify the identifier in the request path and resend the request with a valid identifier.
`422 Unprocessable Entity`	Validation Error	Review the request parameters or body, correct the invalid values, and resend the request.

Create an entity export for a conversation job

The Create an entity export for a conversation job API returns create an entity export for a conversation job. Use this operation to create an entity export for a conversation job.

HTTP method and endpoint

Use the following HTTP method and endpoint path to create an entity export for a conversation job.

POST {TenantURL}/ai/agentflow/api/v202605/{tenant_id}/lrt/jobs/{conversation_id}/entities/export

The following table describes the endpoint path parameters.


Parameter	Type	Required	Description
`TenantURL`	String	Yes	The base URL for your tenant.
`conversation_id`	String	Yes	-
`tenant_id`	String	Yes	The tenant identifier.

Request headers

The following request headers must be included.


Header	Value	Required
`Authorization`	`<access_token>`	Yes
`Content-Type`	application/json	Yes

Request body

The following table describes the request body parameters.


Parameter	Type	Required	Description	Accepted values / Default
format	String	No	-	`csv`, `jsonl`. Default: `csv`
status	String	No	-	-
confidence	String	No	-	-
include_conversation	Boolean	No	-	Default: `false`

Example request

Use the following example to see how a complete request is structured, with headers and a JSON body.

POST {TenantURL}/ai/agentflow/api/v202605/tenant-xyz/lrt/jobs/example-id/entities/export
Authorization: <access_token>
Content-Type: application/json

{
  "format": "<string>",
  "status": "<string>",
  "confidence": "<string>",
  "include_conversation": false
}

Response body

The following table describes the fields returned in the response body.


Parameter	Type	Description
`export_id`	String	-
`status`	String	-
`format`	String	-
`include_conversation`	Boolean	-
`filters`	Object	-
`filters.status`	String	-
`filters.confidence`	String	-
`total_count`	Integer	-
`written_rows`	Integer	-
`written_bytes`	Integer	-
`created_at`	String	-
`completed_at`	String	-
`expires_at`	String	-
`filename`	String	-
`download_url`	String	-
`email_sent_at`	String	-
`error_code`	String	-

Example response

The following example shows a response with existing identical export.

{
  "export_id": "<string>",
  "status": "<string>",
  "format": "<string>",
  "include_conversation": false,
  "filters": {
    "status": "<string>",
    "confidence": "<string>"
  },
  "total_count": 0,
  "written_rows": 0,
  "written_bytes": 0,
  "created_at": "<string>",
  "completed_at": "<string>",
  "expires_at": "<string>",
  "filename": "<string>",
  "download_url": "<string>",
  "email_sent_at": "<string>",
  "error_code": "<string>"
}

Error codes and recommended actions

The following table lists the possible error responses returned by this API.


HTTP status	Description	Recommended action
`404 Not Found`	Job not found	Verify the identifier in the request path and resend the request with a valid identifier.
`409 Conflict`	Job has not reached a terminal state	Wait until the job reaches a terminal state, then resend the request.
`422 Unprocessable Entity`	Validation Error	Review the request parameters or body, correct the invalid values, and resend the request.

Get entity export status and download URL

The Get entity export status and download URL API returns get entity export status and download url. Use this operation to get entity export status and download URL.

HTTP method and endpoint

Use the following HTTP method and endpoint path to get entity export status and download URL.

GET {TenantURL}/ai/agentflow/api/v202605/{tenant_id}/lrt/jobs/{conversation_id}/entities/export/{export_id}

The following table describes the endpoint path parameters.


Parameter	Type	Required	Description
`TenantURL`	String	Yes	The base URL for your tenant.
`conversation_id`	String	Yes	-
`export_id`	String	Yes	-
`tenant_id`	String	Yes	The tenant identifier.

Request headers

The following request headers must be included.


Header	Value	Required
`Authorization`	`<access_token>`	Yes

Request body

This operation does not require a request body.

Example request

Use the following example to see how a complete request is structured, with headers.

GET {TenantURL}/ai/agentflow/api/v202605/tenant-xyz/lrt/jobs/example-id/entities/export/example-id
Authorization: <access_token>

Response body

The following table describes the fields returned in the response body.


Parameter	Type	Description
`export_id`	String	-
`status`	String	-
`format`	String	-
`include_conversation`	Boolean	-
`filters`	Object	-
`filters.status`	String	-
`filters.confidence`	String	-
`total_count`	Integer	-
`written_rows`	Integer	-
`written_bytes`	Integer	-
`created_at`	String	-
`completed_at`	String	-
`expires_at`	String	-
`filename`	String	-
`download_url`	String	-
`email_sent_at`	String	-
`error_code`	String	-

Example response

The following example shows a response with successful response.

{
  "export_id": "<string>",
  "status": "<string>",
  "format": "<string>",
  "include_conversation": false,
  "filters": {
    "status": "<string>",
    "confidence": "<string>"
  },
  "total_count": 0,
  "written_rows": 0,
  "written_bytes": 0,
  "created_at": "<string>",
  "completed_at": "<string>",
  "expires_at": "<string>",
  "filename": "<string>",
  "download_url": "<string>",
  "email_sent_at": "<string>",
  "error_code": "<string>"
}

Error codes and recommended actions

The following table lists the possible error responses returned by this API.


HTTP status	Description	Recommended action
`422 Unprocessable Entity`	Validation Error	Review the request parameters or body, correct the invalid values, and resend the request.

Unify and manage your data

Manage entity results and exports

Entity status counts for a conversation

Paginated per-entity results for a conversation

Full detail for a single entity in a conversation

List entity exports for a conversation job

Create an entity export for a conversation job

Get entity export status and download URL

Footer