Poll a composer session
curl --request GET \
--url https://api.instaview.sk/agents/composer/{sessionId} \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.instaview.sk/agents/composer/{sessionId}"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.instaview.sk/agents/composer/{sessionId}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.instaview.sk/agents/composer/{sessionId}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.instaview.sk/agents/composer/{sessionId}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.instaview.sk/agents/composer/{sessionId}")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.instaview.sk/agents/composer/{sessionId}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"sessionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"status": "processing",
"messages": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"role": "user",
"content": "Your agent opens by introducing itself and confirming it's speaking with the right person. It then works through Go and Postgres experience…",
"createdAt": "2023-11-07T05:31:56Z",
"changes": [
"Added a relocation question",
"Set the language to Slovak"
]
}
],
"expiresAt": "2023-11-07T05:31:56Z",
"agent": {
"type": "ONLINE",
"flow": {
"firstMessage": {
"type": "first_message",
"text": "Hi {{contact.firstName}}, do you have two minutes?",
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"label": "Qualify budget"
},
"sections": [
{
"type": "sequential",
"prompt": "Introduce yourself and explain why you are calling.",
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"label": "Qualify budget"
}
],
"lastMessage": {
"type": "last_message",
"text": "Thanks for your time — have a great day!",
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"label": "Qualify budget"
},
"schemaVersion": "1.0.0"
},
"name": "Senior Developer Phone Screen",
"language": "EN",
"duration": 123,
"voiceId": "<string>",
"backgroundSound": "OFFICE",
"companyPhoneNumberId": "<string>",
"metadata": {},
"overrides": {
"companyName": "Acme Manufacturing",
"companyDescription": "Acme makes industrial fasteners and employs 400 people across Slovakia."
},
"guardrails": {
"rules": [
"Never quote a price",
"Never promise a delivery date"
]
},
"contextConfig": {
"role": "an account executive for Acme",
"communicationStyle": "concise and direct",
"callToAction": "book a 30-minute demo",
"useContactContext": true
},
"analyticsConfig": {
"extractionTargets": [
{
"label": "Budget confirmed",
"type": "bool",
"key": "budget_confirmed",
"enumValues": [
"hot",
"warm",
"cold"
],
"ideal": "A confirmed budget of at least 10k",
"importance": "PREFERRED",
"weight": 40
}
],
"scoringCriteria": [
{
"label": "Handled objections",
"description": "Acknowledged the objection and answered it with a concrete example",
"key": "handled_objections",
"importance": "PREFERRED",
"weight": 40
}
],
"outcomes": [
{
"label": "Meeting booked",
"description": "The contact agreed to a specific date and time",
"key": "meeting_booked"
}
],
"outputTags": [
{
"label": "Needs follow-up",
"key": "needs_followup",
"description": "The contact asked to be called back"
}
],
"capture": {
"recording": true,
"transcript": true,
"summary": true,
"qa": true,
"evaluation": true,
"sentiment": true
}
},
"callConfig": {
"retryPolicy": {
"maxAttempts": 3
},
"callWindow": {
"days": [
"mon",
"tue",
"wed",
"thu",
"fri"
],
"start": "09:00",
"end": "18:00",
"timezoneAnchor": {
"mode": "contact",
"timezone": "Europe/Bratislava",
"fallbackTimezone": "Europe/Bratislava"
}
}
}
},
"nextCursor": "<string>",
"error": {
"code": "COMPOSER_INVALID_RESULT",
"message": "<string>",
"details": [
{}
]
}
}{
"sessionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"status": "processing",
"messages": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"role": "user",
"content": "Your agent opens by introducing itself and confirming it's speaking with the right person. It then works through Go and Postgres experience…",
"createdAt": "2023-11-07T05:31:56Z",
"changes": [
"Added a relocation question",
"Set the language to Slovak"
]
}
],
"expiresAt": "2023-11-07T05:31:56Z",
"agent": {
"type": "ONLINE",
"flow": {
"firstMessage": {
"type": "first_message",
"text": "Hi {{contact.firstName}}, do you have two minutes?",
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"label": "Qualify budget"
},
"sections": [
{
"type": "sequential",
"prompt": "Introduce yourself and explain why you are calling.",
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"label": "Qualify budget"
}
],
"lastMessage": {
"type": "last_message",
"text": "Thanks for your time — have a great day!",
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"label": "Qualify budget"
},
"schemaVersion": "1.0.0"
},
"name": "Senior Developer Phone Screen",
"language": "EN",
"duration": 123,
"voiceId": "<string>",
"backgroundSound": "OFFICE",
"companyPhoneNumberId": "<string>",
"metadata": {},
"overrides": {
"companyName": "Acme Manufacturing",
"companyDescription": "Acme makes industrial fasteners and employs 400 people across Slovakia."
},
"guardrails": {
"rules": [
"Never quote a price",
"Never promise a delivery date"
]
},
"contextConfig": {
"role": "an account executive for Acme",
"communicationStyle": "concise and direct",
"callToAction": "book a 30-minute demo",
"useContactContext": true
},
"analyticsConfig": {
"extractionTargets": [
{
"label": "Budget confirmed",
"type": "bool",
"key": "budget_confirmed",
"enumValues": [
"hot",
"warm",
"cold"
],
"ideal": "A confirmed budget of at least 10k",
"importance": "PREFERRED",
"weight": 40
}
],
"scoringCriteria": [
{
"label": "Handled objections",
"description": "Acknowledged the objection and answered it with a concrete example",
"key": "handled_objections",
"importance": "PREFERRED",
"weight": 40
}
],
"outcomes": [
{
"label": "Meeting booked",
"description": "The contact agreed to a specific date and time",
"key": "meeting_booked"
}
],
"outputTags": [
{
"label": "Needs follow-up",
"key": "needs_followup",
"description": "The contact asked to be called back"
}
],
"capture": {
"recording": true,
"transcript": true,
"summary": true,
"qa": true,
"evaluation": true,
"sentiment": true
}
},
"callConfig": {
"retryPolicy": {
"maxAttempts": 3
},
"callWindow": {
"days": [
"mon",
"tue",
"wed",
"thu",
"fri"
],
"start": "09:00",
"end": "18:00",
"timezoneAnchor": {
"mode": "contact",
"timezone": "Europe/Bratislava",
"fallbackTimezone": "Europe/Bratislava"
}
}
}
},
"nextCursor": "<string>",
"error": {
"code": "COMPOSER_INVALID_RESULT",
"message": "<string>",
"details": [
{}
]
}
}Agents
Poll a Composer Session
The session’s status, its current preview and its conversation, newest first. This is what you poll after starting or refining: 202 while a turn is running, 200 once it has finished.
GET
/
agents
/
composer
/
{sessionId}
Poll a composer session
curl --request GET \
--url https://api.instaview.sk/agents/composer/{sessionId} \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.instaview.sk/agents/composer/{sessionId}"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.instaview.sk/agents/composer/{sessionId}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.instaview.sk/agents/composer/{sessionId}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.instaview.sk/agents/composer/{sessionId}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.instaview.sk/agents/composer/{sessionId}")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.instaview.sk/agents/composer/{sessionId}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"sessionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"status": "processing",
"messages": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"role": "user",
"content": "Your agent opens by introducing itself and confirming it's speaking with the right person. It then works through Go and Postgres experience…",
"createdAt": "2023-11-07T05:31:56Z",
"changes": [
"Added a relocation question",
"Set the language to Slovak"
]
}
],
"expiresAt": "2023-11-07T05:31:56Z",
"agent": {
"type": "ONLINE",
"flow": {
"firstMessage": {
"type": "first_message",
"text": "Hi {{contact.firstName}}, do you have two minutes?",
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"label": "Qualify budget"
},
"sections": [
{
"type": "sequential",
"prompt": "Introduce yourself and explain why you are calling.",
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"label": "Qualify budget"
}
],
"lastMessage": {
"type": "last_message",
"text": "Thanks for your time — have a great day!",
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"label": "Qualify budget"
},
"schemaVersion": "1.0.0"
},
"name": "Senior Developer Phone Screen",
"language": "EN",
"duration": 123,
"voiceId": "<string>",
"backgroundSound": "OFFICE",
"companyPhoneNumberId": "<string>",
"metadata": {},
"overrides": {
"companyName": "Acme Manufacturing",
"companyDescription": "Acme makes industrial fasteners and employs 400 people across Slovakia."
},
"guardrails": {
"rules": [
"Never quote a price",
"Never promise a delivery date"
]
},
"contextConfig": {
"role": "an account executive for Acme",
"communicationStyle": "concise and direct",
"callToAction": "book a 30-minute demo",
"useContactContext": true
},
"analyticsConfig": {
"extractionTargets": [
{
"label": "Budget confirmed",
"type": "bool",
"key": "budget_confirmed",
"enumValues": [
"hot",
"warm",
"cold"
],
"ideal": "A confirmed budget of at least 10k",
"importance": "PREFERRED",
"weight": 40
}
],
"scoringCriteria": [
{
"label": "Handled objections",
"description": "Acknowledged the objection and answered it with a concrete example",
"key": "handled_objections",
"importance": "PREFERRED",
"weight": 40
}
],
"outcomes": [
{
"label": "Meeting booked",
"description": "The contact agreed to a specific date and time",
"key": "meeting_booked"
}
],
"outputTags": [
{
"label": "Needs follow-up",
"key": "needs_followup",
"description": "The contact asked to be called back"
}
],
"capture": {
"recording": true,
"transcript": true,
"summary": true,
"qa": true,
"evaluation": true,
"sentiment": true
}
},
"callConfig": {
"retryPolicy": {
"maxAttempts": 3
},
"callWindow": {
"days": [
"mon",
"tue",
"wed",
"thu",
"fri"
],
"start": "09:00",
"end": "18:00",
"timezoneAnchor": {
"mode": "contact",
"timezone": "Europe/Bratislava",
"fallbackTimezone": "Europe/Bratislava"
}
}
}
},
"nextCursor": "<string>",
"error": {
"code": "COMPOSER_INVALID_RESULT",
"message": "<string>",
"details": [
{}
]
}
}{
"sessionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"status": "processing",
"messages": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"role": "user",
"content": "Your agent opens by introducing itself and confirming it's speaking with the right person. It then works through Go and Postgres experience…",
"createdAt": "2023-11-07T05:31:56Z",
"changes": [
"Added a relocation question",
"Set the language to Slovak"
]
}
],
"expiresAt": "2023-11-07T05:31:56Z",
"agent": {
"type": "ONLINE",
"flow": {
"firstMessage": {
"type": "first_message",
"text": "Hi {{contact.firstName}}, do you have two minutes?",
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"label": "Qualify budget"
},
"sections": [
{
"type": "sequential",
"prompt": "Introduce yourself and explain why you are calling.",
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"label": "Qualify budget"
}
],
"lastMessage": {
"type": "last_message",
"text": "Thanks for your time — have a great day!",
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"label": "Qualify budget"
},
"schemaVersion": "1.0.0"
},
"name": "Senior Developer Phone Screen",
"language": "EN",
"duration": 123,
"voiceId": "<string>",
"backgroundSound": "OFFICE",
"companyPhoneNumberId": "<string>",
"metadata": {},
"overrides": {
"companyName": "Acme Manufacturing",
"companyDescription": "Acme makes industrial fasteners and employs 400 people across Slovakia."
},
"guardrails": {
"rules": [
"Never quote a price",
"Never promise a delivery date"
]
},
"contextConfig": {
"role": "an account executive for Acme",
"communicationStyle": "concise and direct",
"callToAction": "book a 30-minute demo",
"useContactContext": true
},
"analyticsConfig": {
"extractionTargets": [
{
"label": "Budget confirmed",
"type": "bool",
"key": "budget_confirmed",
"enumValues": [
"hot",
"warm",
"cold"
],
"ideal": "A confirmed budget of at least 10k",
"importance": "PREFERRED",
"weight": 40
}
],
"scoringCriteria": [
{
"label": "Handled objections",
"description": "Acknowledged the objection and answered it with a concrete example",
"key": "handled_objections",
"importance": "PREFERRED",
"weight": 40
}
],
"outcomes": [
{
"label": "Meeting booked",
"description": "The contact agreed to a specific date and time",
"key": "meeting_booked"
}
],
"outputTags": [
{
"label": "Needs follow-up",
"key": "needs_followup",
"description": "The contact asked to be called back"
}
],
"capture": {
"recording": true,
"transcript": true,
"summary": true,
"qa": true,
"evaluation": true,
"sentiment": true
}
},
"callConfig": {
"retryPolicy": {
"maxAttempts": 3
},
"callWindow": {
"days": [
"mon",
"tue",
"wed",
"thu",
"fri"
],
"start": "09:00",
"end": "18:00",
"timezoneAnchor": {
"mode": "contact",
"timezone": "Europe/Bratislava",
"fallbackTimezone": "Europe/Bratislava"
}
}
}
},
"nextCursor": "<string>",
"error": {
"code": "COMPOSER_INVALID_RESULT",
"message": "<string>",
"details": [
{}
]
}
}Whether the session is still working, the agent it is currently holding, and the conversation that shaped it.
This is what you poll after designing or refining an agent — both of those answer
The body is the same either way, so a poll loop can branch on the code alone and only parse once it gets a
The pattern behind that last column: a session never loses an agent it once had. Only the first turn can leave you with no preview, because there was none to fall back on. Everything after that either improves the agent or leaves it exactly as it was.
So a
No
202 and finish in the background. It is also how you pick up a session your integration started earlier, after a page reload, in another process, or when a human comes back to a preview a day later.
The status code is the answer
| Code | Meaning |
|---|---|
202 | A turn is running. Poll again; every five seconds is plenty |
200 | The turn has finished — status is ready or failed |
200.
{
"sessionId": "9f8c1d2e-4b7a-4c3d-9e1f-2a5b6c7d8e90",
"status": "ready",
"agent": { "name": "Senior Backend Phone Screen", "type": "PHONE", "flow": { "…": "…" } },
"messages": [
{
"id": "…",
"role": "assistant",
"content": "Your agent now asks about relocation, and the whole call is in Slovak.",
"changes": ["Added a relocation question", "Set the language to SK"],
"createdAt": "2026-08-18T10:22:00.000Z"
},
{ "id": "…", "role": "user", "content": "Also ask about relocation, and make the whole call Slovak.", "createdAt": "2026-08-18T10:22:00.000Z" }
],
"expiresAt": "2026-09-17T10:15:00.000Z"
}
agent is the current preview — the same body POST /agents accepts verbatim, reflecting every refinement so far.
The three states
status | What it means | Is agent there? |
|---|---|---|
processing | A turn is running | Yes, unless this is the first turn |
ready | The last turn succeeded | Yes |
failed | The last turn produced nothing; see error | Yes, unless the first turn is the one that failed |
processing session that already has an agent is showing you the one your last successful turn produced, and it is still postable while the next change is being applied.
While a turn is in flight
The conversation ends on your own message, with no reply under it yet. That is not a gap in the data — the question has been asked and not yet answered. When the turn lands, the reply appears; when it fails, the question stays standing anderror says why, rather than an invented answer appearing beneath it.
Paging the conversation
messages is newest first. When there is an older page, nextCursor is present; pass it back as cursor to continue.
GET /agents/composer/{sessionId}?cursor=MjAyNi0wOC0xOFQxMDoyMjowMC4wMDBafG1zZy0x
nextCursor means you have reached the beginning of the conversation.
The cursor is opaque. Do not construct or parse one — pass back what you were given. An
unreadable cursor is treated as no cursor, so you get the newest page rather than an error.
Scope and lifetime
Requires theagents read scope. An unknown session, an expired one, and one belonging to another company are all a 404.
Sessions live 30 days; expiresAt says when this one goes. Once you create the agent, the conversation moves with it and is no longer read here — it is part of the agent.Authorizations
API key for authentication using Bearer scheme
Path Parameters
The composer session id returned by POST /agents/composer.
Query Parameters
Opaque cursor from a previous page's nextCursor.
Required for ATS API keys to specify which company to access. Ignored for standard company API keys.
Response
The turn has finished. status is ready (the preview is in agent) or failed (see error).
processing while a turn is running, ready when agent is a preview you can create from, failed when the last turn did not produce one (see error).
Available options:
processing, ready, failed The conversation so far, newest first.
Show child attributes
Show child attributes
The agent this session would create. Absent only until the FIRST turn produces one; after that it is the last good preview, even while a later turn is running or has failed.
Show child attributes
Show child attributes
Pass as cursor to fetch the next (older) page. Absent at the start of the conversation.
Show child attributes
Show child attributes