Goals API
A goal is a yes/no outcome an agent should reach in a conversation, such as a booked meeting. It belongs to an agent, is evaluated on one of the agent's channels, and its targets set how many achieved conversations, or what share, count as on track per period.
goals:readgoals:write7 endpointsShow
Which conversations are evaluated
The channel decides: read its automatic evaluation and sample rate with GET /v1/channels/:id, and change them with PATCH /v1/channels/:id. Each agent's results are read with GET /v1/agents/:id/goals/progress, against the targets, and GET /v1/agents/:id/goals/analytics, over time or comparing two of its versions.
/v1/goalsList goals
Lists evaluation goals with their targets, newest first.
goals:readQuery parameters
limitinteger · 1–100Results per page. Default: 20.
offsetinteger · at least 0Results to skip. Default: 0.
agent_iduuidOnly this agent's goals.
channel_iduuidOnly goals evaluated on this channel.
activebooleanOnly active (true) or inactive (false) goals.
Show 1 more field
Errors
400validation_errorA query parameter is invalid (details.errors lists each one).Plus the errors every request can return (401, 403, 429, 500): Errors.
curl "https://www.nutalk.ai/v1/goals?active=true&limit=10" \ -H "Authorization: Bearer $NUTALK_API_KEY"
{
"success": true,
"data": [
{
"id": "7b7b8def-a340-4bfd-b164-779fa5843735",
"agent_id": "550e8400-e29b-41d4-a716-446655440000",
"channel_id": "9f19ef32-eaef-452c-bebc-14d9759cdb64",
"title": "Book qualified meeting",
"description": "The call ends with a confirmed meeting time.",
"active": true,
"created_at": "2026-10-02T02:25:39.039843+00:00",
"updated_at": "2026-10-02T02:25:39.039843+00:00",
"goal_targets": [
{
"id": "0d89e7b2-6025-4ce7-8733-033c2f74fd72",
"period": "week",
"target_type": "count",
"target_count": 25,
"target_rate": null,
"is_primary": true,
"created_at": "2026-10-02T02:25:39.044751+00:00",
"updated_at": "2026-10-02T02:25:39.044751+00:00"
}
]
}
],
"pagination": {
"total": 1,
"limit": 10,
"offset": 0,
"has_more": false
}
}/v1/goalsCreate a goal
Creates a binary success goal for an agent, evaluated on one of the agent's channels. After each evaluated conversation the evaluator records whether the goal was achieved; targets set how many (or what share) per period count as on track.
goals:writeRequest body
agent_iduuidrequiredThe agent the goal belongs to.
channel_iduuid | nullA channel the agent is on. Optional when the agent is on exactly one channel (that one is used); required when it is on several (the error lists them).
titlestring · 1–200 charactersrequiredShort name.
descriptionstring · 1–5,000 charactersrequiredWhat success looks like: the evaluator judges each conversation against it.
activebooleanInactive goals are not evaluated. Default: true.
targetsobject[]Period targets.
targets[].periodday | week | month | quarter | semester | yearrequiredThe period the target counts over.
targets[].target_typecount | raterequiredcount: a number of achieved conversations per period; rate: a percentage of evaluated conversations.
targets[].target_countinteger | null · at least 1Required for count targets (and only for them).
targets[].target_ratenumber | null · at most 100Required for rate targets (and only for them): a percentage above 0, at most 100.
targets[].is_primarybooleanThe target shown first. Default: false.
Show 7 more fields
Errors
400validation_errorThe body is not JSON, or a field is missing or invalid (details.errors lists each field).404not_foundNo agent with this id in your workspace (ids of other workspaces answer the same).404not_foundchannel_id is not a channel of your workspace.400validation_errorThe agent is on no channel or on several and channel_id is missing (details.bound_channel_ids), or channel_id is not one of the agent's channels.409validation_errorThe agent already has a goal with this title on this channel.Plus the errors every request can return (401, 403, 429, 500): Errors.
curl -X POST https://www.nutalk.ai/v1/goals \
-H "Authorization: Bearer $NUTALK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"agent_id": "550e8400-e29b-41d4-a716-446655440000",
"channel_id": "9f19ef32-eaef-452c-bebc-14d9759cdb64",
"title": "Book qualified meeting",
"description": "The call ends with a confirmed meeting time.",
"targets": [
{
"period": "week",
"target_type": "count",
"target_count": 25,
"is_primary": true
}
]
}'{
"success": true,
"data": {
"id": "7b7b8def-a340-4bfd-b164-779fa5843735",
"agent_id": "550e8400-e29b-41d4-a716-446655440000",
"channel_id": "9f19ef32-eaef-452c-bebc-14d9759cdb64",
"title": "Book qualified meeting",
"description": "The call ends with a confirmed meeting time.",
"active": true,
"created_at": "2026-10-02T02:25:39.039843+00:00",
"updated_at": "2026-10-02T02:25:39.039843+00:00",
"goal_targets": [
{
"id": "0d89e7b2-6025-4ce7-8733-033c2f74fd72",
"period": "week",
"target_type": "count",
"target_count": 25,
"target_rate": null,
"is_primary": true,
"created_at": "2026-10-02T02:25:39.044751+00:00",
"updated_at": "2026-10-02T02:25:39.044751+00:00"
}
]
}
}/v1/goals/:idGet a goal
Returns one goal with its targets.
goals:readPath parameters
iduuidrequiredThe goal id.
Errors
404not_foundNo goal with this id in your workspace (ids of other workspaces answer the same).Plus the errors every request can return (401, 403, 429, 500): Errors.
curl https://www.nutalk.ai/v1/goals/7b7b8def-a340-4bfd-b164-779fa5843735 \ -H "Authorization: Bearer $NUTALK_API_KEY"
{
"success": true,
"data": {
"id": "7b7b8def-a340-4bfd-b164-779fa5843735",
"agent_id": "550e8400-e29b-41d4-a716-446655440000",
"channel_id": "9f19ef32-eaef-452c-bebc-14d9759cdb64",
"title": "Book qualified meeting",
"description": "The call ends with a confirmed meeting time.",
"active": true,
"created_at": "2026-10-02T02:25:39.039843+00:00",
"updated_at": "2026-10-02T02:25:39.039843+00:00",
"goal_targets": [
{
"id": "0d89e7b2-6025-4ce7-8733-033c2f74fd72",
"period": "week",
"target_type": "count",
"target_count": 25,
"target_rate": null,
"is_primary": true,
"created_at": "2026-10-02T02:25:39.044751+00:00",
"updated_at": "2026-10-02T02:25:39.044751+00:00"
}
]
}
}/v1/goals/:idUpdate a goal
Changes the fields you send. targets replaces every target of the goal. channel_id may move the goal to another of the agent's channels; it cannot be set to null.
goals:writeCan wait for approvalPath parameters
iduuidrequiredThe goal id.
Request body
titlestring · 1–200 charactersNew title.
descriptionstring · 1–5,000 charactersNew success criteria.
channel_iduuidAnother channel the agent is on.
activebooleanTurn evaluation on or off.
targetsobject[]The goal's new targets (replaces all).
targets[].periodday | week | month | quarter | semester | yearrequiredThe period the target counts over.
targets[].target_typecount | raterequiredcount: a number of achieved conversations per period; rate: a percentage of evaluated conversations.
targets[].target_countinteger | null · at least 1Required for count targets (and only for them).
targets[].target_ratenumber | null · at most 100Required for rate targets (and only for them): a percentage above 0, at most 100.
targets[].is_primarybooleanThe target shown first. Default: false.
Show 6 more fields
Nothing changes yet: the call answers 202 with data.change_request, and runs once an owner or admin approves it in Settings → API keys. Follow it with GET /v1/change-requests/:id.
Errors
400validation_errorThe body is not JSON, or a field is missing or invalid (details.errors lists each field).400validation_errorNo field to change was sent, or channel_id is null or not one of the agent's channels.404not_foundNo goal with this id in your workspace (ids of other workspaces answer the same).404not_foundchannel_id is not a channel of your workspace.409validation_errorThe agent already has a goal with this title on this channel.Plus the errors every request can return (401, 403, 429, 500): Errors.
curl -X PATCH https://www.nutalk.ai/v1/goals/7b7b8def-a340-4bfd-b164-779fa5843735 \
-H "Authorization: Bearer $NUTALK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"active": true,
"targets": [
{
"period": "month",
"target_type": "rate",
"target_rate": 70,
"is_primary": true
}
]
}'{
"success": true,
"data": {
"id": "7b7b8def-a340-4bfd-b164-779fa5843735",
"agent_id": "550e8400-e29b-41d4-a716-446655440000",
"channel_id": "9f19ef32-eaef-452c-bebc-14d9759cdb64",
"title": "Book qualified meeting",
"description": "The call ends with a confirmed meeting time.",
"active": true,
"created_at": "2026-10-02T02:25:39.039843+00:00",
"updated_at": "2026-10-02T02:25:46.779756+00:00",
"goal_targets": [
{
"id": "0d89e7b2-6025-4ce7-8733-033c2f74fd72",
"period": "month",
"target_type": "rate",
"target_count": null,
"target_rate": 70,
"is_primary": true,
"created_at": "2026-10-02T02:25:46.792433+00:00",
"updated_at": "2026-10-02T02:25:46.792433+00:00"
}
]
}
}/v1/goals/:idDelete a goal
Deletes the goal and its targets.
goals:writeWaits for approvalPath parameters
iduuidrequiredThe goal id.
Unless its key was set not to wait, nothing is removed yet: the call answers 202 with data.change_request, and runs once an owner or admin approves it in Settings → API keys. Follow it with GET /v1/change-requests/:id.
Errors
404not_foundNo goal with this id in your workspace (ids of other workspaces answer the same).Plus the errors every request can return (401, 403, 429, 500): Errors.
curl -X DELETE https://www.nutalk.ai/v1/goals/7b7b8def-a340-4bfd-b164-779fa5843735 \ -H "Authorization: Bearer $NUTALK_API_KEY"
{
"success": true,
"data": {
"id": "7b7b8def-a340-4bfd-b164-779fa5843735",
"deleted": true
}
}/v1/agents/:id/goals/progressGet an agent's goal progress
The agent's goals and how each is doing against its targets in the current period (or as of a day, or over a date range): met conversations, evaluated ones, the rate, the share of the target reached and what remains, and each goal's trend. Rates, percent_of_target and trend_value are percentages (0 to 100); remaining_to_target is a sentence. Days are UTC days, and to and as_of count through the end of theirs.
goals:readWorkspace keys only · acts as the key's creatorIt runs the dashboard's own rules as the member who created the key. A key whose creator has left the workspace, and a reseller key, are refused.
Path parameters
iduuidrequiredThe agent id.
Query parameters
channel_iduuidOnly the goals of one of the agent's channels.
as_ofstringThe day the periods are counted at, through its end (default: now) (YYYY-MM-DD).
fromstringWith to: a date range instead of the targets' periods (YYYY-MM-DD).
tostringWith from: the range's last day, counted through its end (YYYY-MM-DD).
Errors
400validation_errorA query parameter is invalid (details.errors lists each one).400validation_errorchannel_id isn't one of the agent's channels.403forbiddenThe member who created the key isn't a member who reads the agent, has left the workspace, or the key is a reseller key.404not_foundNo agent with this id in your workspace (ids of other workspaces answer the same).Plus the errors every request can return (401, 403, 429, 500): Errors.
curl "https://www.nutalk.ai/v1/agents/7b7b8def-a340-4bfd-b164-779fa5843735/goals/progress?as_of=2026-10-28" \ -H "Authorization: Bearer $NUTALK_API_KEY"
{
"success": true,
"data": {
"goals": [
{
"id": "7b7b8def-a340-4bfd-b164-779fa5843735",
"title": "Books an appointment",
"description": "",
"active": true,
"channel_id": "9f19ef32-eaef-452c-bebc-14d9759cdb64",
"channel_name": "Clínica Sol WhatsApp",
"targets": [
{
"id": "5c6d7e8f-9a0b-4c1d-8e2f-3a4b5c6d7e8f",
"period": "month",
"target_type": "rate",
"target_count": null,
"target_rate": 40,
"is_primary": true,
"progress": {
"period_start": "2026-10-01T00:00:00+00:00",
"period_end": "2026-11-01T00:00:00+00:00",
"met_count": 31,
"total_evaluations": 88,
"current_rate": 35.2,
"percent_of_target": 88,
"remaining_to_target": "4.8% more needed"
}
}
],
"stats": {
"total_evaluations": 88,
"met_count": 31,
"success_rate": 35,
"trend": "up",
"trend_value": 6
}
}
],
"as_of": "2026-10-28T23:59:59.999Z"
}
}/v1/agents/:id/goals/analyticsGet an agent's goal analytics
How the agent's goals did over time, by day, week, month or quarter: the totals, a series per goal, and each active goal's rate and recent trend. With compare_version_ids, two versions of the agent side by side instead: each goal's rate on each and the winner. Rates are percentages (0 to 100). Days are UTC days, and to counts through the end of its day.
goals:readWorkspace keys only · acts as the key's creatorIt runs the dashboard's own rules as the member who created the key. A key whose creator has left the workspace, and a reseller key, are refused.
Path parameters
iduuidrequiredThe agent id.
Query parameters
periodday | week | month | quarterThe series' step. Default: month.
channel_iduuidOnly one channel.
version_iduuidOnly one version.
fromstringThe window's first day (default: by period) (YYYY-MM-DD).
tostringThe window's last day, counted through its end (default: now) (YYYY-MM-DD).
compare_version_idsstringTwo different versions, comma-separated: compares them instead.
Show 2 more fields
Errors
400validation_errorA query parameter is invalid (details.errors lists each one).403forbiddenThe member who created the key isn't a member who reads the agent, has left the workspace, or the key is a reseller key.404not_foundNo agent with this id in your workspace (ids of other workspaces answer the same).Plus the errors every request can return (401, 403, 429, 500): Errors.
curl "https://www.nutalk.ai/v1/agents/7b7b8def-a340-4bfd-b164-779fa5843735/goals/analytics?period=week&from=2026-10-01&to=2026-10-28" \ -H "Authorization: Bearer $NUTALK_API_KEY"
{
"success": true,
"data": {
"period": "week",
"date_range": {
"from": "2026-10-01T00:00:00.000Z",
"to": "2026-10-28T23:59:59.999Z"
},
"totals": {
"total_evaluations": 88,
"met_count": 31,
"success_rate": 35
},
"time_series": [],
"goals": []
}
}