curl --request GET \
--url https://api.usenexio.com/api/v1/conversation-instances/{instance_slug}/conversations/{conversation_id}/turns/{turn_id} \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.usenexio.com/api/v1/conversation-instances/{instance_slug}/conversations/{conversation_id}/turns/{turn_id}"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.usenexio.com/api/v1/conversation-instances/{instance_slug}/conversations/{conversation_id}/turns/{turn_id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"turn": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"status": "running",
"started_at": "2023-11-07T05:31:56Z",
"stop_requested_at": "2023-11-07T05:31:56Z",
"ended_at": "2023-11-07T05:31:56Z",
"stop_reason": "<string>"
}
}{
"code": "<string>",
"message": "<string>",
"details": "<unknown>"
}{
"code": "unauthorized",
"message": "Missing or invalid API key"
}{
"code": "<string>",
"message": "<string>",
"details": "<unknown>"
}{
"code": "<string>",
"message": "<string>",
"details": "<unknown>"
}{
"code": "rate_limited",
"message": "Rate limit exceeded"
}{
"code": "internal_error",
"message": "Internal server error"
}{
"code": "auth_unavailable",
"message": "API key authentication is temporarily unavailable"
}{
"code": "request_timeout",
"message": "Request timed out"
}Get a turn
Read one turn’s status: running, paused, stopping, or at rest.
curl --request GET \
--url https://api.usenexio.com/api/v1/conversation-instances/{instance_slug}/conversations/{conversation_id}/turns/{turn_id} \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.usenexio.com/api/v1/conversation-instances/{instance_slug}/conversations/{conversation_id}/turns/{turn_id}"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.usenexio.com/api/v1/conversation-instances/{instance_slug}/conversations/{conversation_id}/turns/{turn_id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"turn": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"status": "running",
"started_at": "2023-11-07T05:31:56Z",
"stop_requested_at": "2023-11-07T05:31:56Z",
"ended_at": "2023-11-07T05:31:56Z",
"stop_reason": "<string>"
}
}{
"code": "<string>",
"message": "<string>",
"details": "<unknown>"
}{
"code": "unauthorized",
"message": "Missing or invalid API key"
}{
"code": "<string>",
"message": "<string>",
"details": "<unknown>"
}{
"code": "<string>",
"message": "<string>",
"details": "<unknown>"
}{
"code": "rate_limited",
"message": "Rate limit exceeded"
}{
"code": "internal_error",
"message": "Internal server error"
}{
"code": "auth_unavailable",
"message": "API key authentication is temporarily unavailable"
}{
"code": "request_timeout",
"message": "Request timed out"
}Behavior
Served only when turn control is on for your environment; until then the route answers404 not_found.
The read changes nothing. Poll it every two seconds while the status is running, waiting_on_tools, waiting_on_confirmation or stopping. An application that runs its own tools reads it before each tool dispatch and starts nothing more once the status is stopping or at rest.
The turn object and its statuses are on Stop a turn.Authorizations
Send the key as Authorization: Bearer <key>. Two kinds of key exist.
Organization keys are issued in the portal (Settings, then API keys),
each bound to one environment, shaped nx_<environment slug>_<64 hex>. They carry
no capabilities and pass every capability check, with one exception:
routes under /records, /actions, /operations,
/api/v1/engines/{id}/opportunities, /api/v1/graph and
/api/v1/catalog/documents accept an
organization key only when its environment is live, and refuse any
other with 403 scoped_key_required. Revocation takes effect within 60
seconds.
Scoped keys are issued by Nexio on request, shaped
nxsk_v1_<24 hex key id>_<43 character secret>. Each is bound to one
org, one environment, a set of engines and a set of capabilities. A
malformed, unknown or revoked nxsk_ key fails with 401 and is never
retried as an organization key. Revocation takes effect on the next
request. A scoped key without a route's capability gets 403
insufficient_capability; a scoped key not bound to the engine gets 403
engine_binding_forbidden.
Key-grantable capabilities: engines:read, runs:write, runs:read,
runs:defensibility:read, runs:test, catalog:read,
catalog:documents:read, webhooks:manage, conversations:use,
conversations:export, records:read, records:opportunities:run,
actions:write, actions:read, graph:read, records:analyze.
Routes that accept organization keys only (every scoped key gets 403
insufficient_capability): environment management, engine create,
update, configuration and publish, and conversation instance
authoring. Each operation description names the capability a scoped
key needs.
Path Parameters
Conversation instance identifier slug (e.g. platform-assistant).
The turn id, from the turn_id of the conversation frame or of a stored message.
Query Parameters
The asserted end-user identity the conversation must belong to. Missing or blank answers 400 invalid_request; another end user's value answers 404 conversation_not_found.
Response
The turn.
The body of the turn read and of Stop.
One turn of a conversation, as served by conversation detail, the
turn read and Stop. status is derived when it is read: a turn not
at rest whose stop was requested is stopping, and a handoff paused
10 minutes or more with no stop requested is failed with
stop_reason handoff_lost. completed, stopped and failed
are at rest.
Hide child attributes
Hide child attributes
The turn id, equal to turn_id on the conversation frame and on every stored message of the turn.
running, waiting_on_tools, waiting_on_confirmation, stopping, completed, stopped, failed When the turn's user message was stored.
When Stop was first requested. A repeated Stop does not move it.
When the turn came to rest.
Null until the turn is at rest. Then the model's stop reason
(such as end_turn), stopped (the user stopped it),
handoff_lost (client tool results never arrived within 10
minutes), segment_lost (the segment running it died), or the
error code of a failed turn.