List campaigns

List the organization's call campaigns, newest first, each with its progress (recipients pending, in progress, completed, failed and succeeded). Filter by status or agentId. A campaign's calls: list_conversations with campaignId; its numbers by day: get_report with name: campaign_progress.

Scopes: any one of raiz:campaigns:read, raiz:campaigns:write
Credentials: an API key, a client-credentials token or a person's access token
Effect: read-only; safe to retry
Limits: response up to 1 MB
CLI: arbol raiz campaigns list · MCP tool: raiz_campaigns_list

GET

https://api.getarbol.com/v1/raiz/campaigns

Authorization

Authorization
string
required
Bearer <token>, where the token is an API key, a client-credentials token or a person's access token with any one of the scopes raiz:campaigns:read, raiz:campaigns:write. Get an API key.

Query parameters

cursor
optional
string
Opaque cursor returned by pageInfo; omit it to request the first page.
direction
optional
forward
or
backward
Direction to traverse the stable keyset ordering from the supplied cursor.

default: "forward"
limit
optional
integer
Maximum items returned in one page. Defaults to 25; larger reads require another cursor.

maximum: 100 · minimum: 1 · default: 25
agentId
optional
string
Agent id.

pattern: ^agt_(?:[0-7][0-9a-hjkmnp-tv-z]{25}|(?:[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}|[a-f0-9]{32}))$
status
optional
queued
or
running
or
paused
or
completed
or
cancelled
or
failed
queued: not started yet (or its start is scheduled). running: calling due recipients. paused: started, then paused; calls in progress finish. completed: no recipient is left to call.

Returns

200

Successful operation.

JSON

success
boolean
required
data
object
required
- data
  array of
  object
  required
  Items admitted by this resource contract within the verified organization.
  
  agentId
  string
  required
  Agent id.
  
  pattern: ^agt_(?:[0-7][0-9a-hjkmnp-tv-z]{25}|(?:[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}|[a-f0-9]{32}))$
  channelId
  string | null
  required
  The voice line calls leave from. Null: the Agent's own outbound line.
  
  pattern: ^(?:chn_(?:[0-7][0-9a-hjkmnp-tv-z]{25}|(?:[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}|[a-f0-9]{32}))|(?:agc)_(?:[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}|[a-f0-9]{32}))$
  contactHours
  array of
  object
  required
  When calls may start, in the campaign's time zone. Empty: any time.
  
  days
  array of
  MO
  or
  TU
  or
  WE
  or
  TH
  or
  FR
  or
  SA
  +1 more
  required
  from
  string
  required
  Local start time, HH:MM, inclusive.
  
  pattern: ^([01][0-9]|2[0-3]):[0-5][0-9]$
  to
  string
  required
  Local end time, HH:MM, exclusive (24:00 for midnight).
  
  pattern: ^(([01][0-9]|2[0-3]):[0-5][0-9]|24:00)$
  createdAt
  string
  required
  An instant in RFC 3339 format, in UTC.
  
  format: date-time
  endedAt
  string | null
  required
  An instant in RFC 3339 format, in UTC.
  
  format: date-time
  firstMessage
  string | null
  required
  id
  string
  required
  Campaign id.
  
  pattern: ^cmp_(?:[0-7][0-9a-hjkmnp-tv-z]{25}|(?:[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}|[a-f0-9]{32}))$
  instructions
  string | null
  required
  maxAttempts
  integer
  required
  maximum: 10 · minimum: 1
  metadata
  object
  required
  Your own keys and labels for this resource (up to 50 keys of 40 characters; values up to 500 characters). Raíz never interprets them.
  
  name
  string
  required
  progress
  object
  required
  How many recipients are in each state.
  
  completed
  integer
  required
  minimum: 0
  failed
  integer
  required
  minimum: 0
  inProgress
  integer
  required
  minimum: 0
  pending
  integer
  required
  minimum: 0
  recipients
  integer
  required
  minimum: 0
  succeeded
  integer
  required
  Recipients whose latest call's analysis judged it successful.
  
  minimum: 0
  retryAfterMinutes
  integer
  required
  minimum: 1
  retryOn
  array of
  no_answer
  or
  failure
  required
  scheduledEndAt
  string | null
  required
  An instant in RFC 3339 format, in UTC.
  
  format: date-time
  scheduledStartAt
  string | null
  required
  An instant in RFC 3339 format, in UTC.
  
  format: date-time
  startedAt
  string | null
  required
  An instant in RFC 3339 format, in UTC.
  
  format: date-time
  status
  queued
  or
  running
  or
  paused
  or
  completed
  or
  cancelled
  or
  failed
  required
  queued: not started yet (or its start is scheduled). running: calling due recipients. paused: started, then paused; calls in progress finish. completed: no recipient is left to call.
  
  timeZone
  string
  required
  updatedAt
  string
  required
  An instant in RFC 3339 format, in UTC.
  
  format: date-time
  version
  integer
  required
  minimum: 1
  recipients
  optional
  object
  The campaign's recipients in the order they were added, each with its latest attempt. Present only when expanded.
  
  data
  array of
  object
  required
  Items admitted by this resource contract within the verified organization.
  
  address
  string
  required
  attemptCount
  integer
  required
  minimum: 0
  contactId
  string | null
  required
  Contact id.
  
  pattern: ^cnt_(?:[0-7][0-9a-hjkmnp-tv-z]{25}|(?:[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}|[a-f0-9]{32}))$
  createdAt
  string
  required
  An instant in RFC 3339 format, in UTC.
  
  format: date-time
  errorCode
  string | null
  required
  Why the recipient failed: NO_ANSWER or CALL_FAILED after its last attempt, CONTACT_SUPPRESSED when a suppression rule forbids the number.
  
  firstMessage
  string | null
  required
  id
  string
  required
  Campaign recipient id.
  
  pattern: ^rcp_(?:[0-7][0-9a-hjkmnp-tv-z]{25}|(?:[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}|[a-f0-9]{32}))$
  instructions
  string | null
  required
  lastAttempt
  object | null
  required
  The latest call to this recipient; its transcript is getConversation.
  
  conversationId
  string
  required
  Conversation id.
  
  pattern: ^cnv_(?:[0-7][0-9a-hjkmnp-tv-z]{25}|(?:[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}|[a-f0-9]{32}))$
  outcome
  success
  or
  failure
  or
  unknown
  or
  null
  required
  startedAt
  string
  required
  An instant in RFC 3339 format, in UTC.
  
  format: date-time
  status
  open
  or
  closed
  required
  nextAttemptAt
  string | null
  required
  An instant in RFC 3339 format, in UTC.
  
  format: date-time
  status
  pending
  or
  in_progress
  or
  completed
  or
  failed
  or
  cancelled
  required
  pending: waiting for its (next) call. in_progress: being called. completed: an attempt succeeded. failed: its attempts ran out, or it cannot be called.
  
  updatedAt
  string
  required
  An instant in RFC 3339 format, in UTC.
  
  format: date-time
  variables
  object
  required
  Values for the {{name}} variables the Agent's instructions, first message or this campaign's texts reference. Raíz always provides contact_name, contact_given_name, contact_id, contact_phone, conversation_id and bulletins (the business bulletins in force), which a recipient's values never replace.
  
  object
  string
  required
  Discriminator for a resource list response.
  
  pageInfo
  object
  required
  Opaque navigation cursors for this page’s stable keyset order.
  
  hasNextPage
  boolean
  required
  Whether a later page exists in the current ordering.
  
  hasPreviousPage
  boolean
  required
  Whether an earlier page exists in the current ordering.
  
  nextCursor
  string | null
  required
  Opaque cursor for the next page, or null when there is none.
  
  previousCursor
  string | null
  required
  Opaque cursor for the previous page, or null when there is none.
- object
  string
  required
  Discriminator for a resource list response.
- pageInfo
  object
  required
  Opaque navigation cursors for this page’s stable keyset order.
  
  hasNextPage
  boolean
  required
  Whether a later page exists in the current ordering.
  
  hasPreviousPage
  boolean
  required
  Whether an earlier page exists in the current ordering.
  
  nextCursor
  string | null
  required
  Opaque cursor for the next page, or null when there is none.
  
  previousCursor
  string | null
  required
  Opaque cursor for the previous page, or null when there is none.
}
error
null
required
metadata
object
required
- requestId
  string
  required
  Request correlation identifier, also sent as X-Request-Id.
}

400

INVALID_INPUT: The request does not match the published schema.
INVALID_CURSOR: The cursor is malformed or belongs to a different list.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

401

UNAUTHORIZED: A valid access token is required.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

403

FORBIDDEN: The token does not authorize this operation.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

404

NOT_FOUND: The requested operation does not exist.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

405

HTTP_METHOD_NOT_ALLOWED: The HTTP method is not supported for this resource.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

413

REQUEST_TOO_LARGE: The request exceeds the allowed size.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

415

UNSUPPORTED_MEDIA_TYPE: The request content type is not supported.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

429

RATE_LIMITED: The request rate limit was exceeded. Try again later.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

500

INTERNAL_ERROR: The service could not complete the operation.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

502

OUTCOME_UNKNOWN: The operation may have been applied; check its result before repeating it.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

503

UPSTREAM_UNAVAILABLE: The upstream service could not complete the request.
INTEGRATIONS_UNAVAILABLE: The organization's integrations cannot be read right now. Try again shortly.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

504

UPSTREAM_TIMEOUT: The upstream service did not respond before its deadline.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}