Get a campaign

Read one campaign: Agent, schedule, contact hours, retries and progress. expand=recipients adds its recipients in the order they were added, each with attempts, next attempt, error and latest call; continue with recipientsCursor (recipientsDirection reads the other way). Read it before update_campaign and send expectedVersion.

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 get · MCP tool: raiz_campaigns_get

GET

https://api.getarbol.com/v1/raiz/campaigns/{campaignId}

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.

Path parameters

campaignId
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}))$

Query parameters

expand
optional
string
Related data to include, comma-separated: recipients.

pattern: ^(recipients)(,(recipients))*$
recipientsCursor
optional
string
Opaque cursor the recipients expansion's pageInfo returned; omit it for its first page.

maxLength: 4096
recipientsDirection
optional
forward
or
backward
Direction to traverse the recipients expansion from the supplied cursor.

default: "forward"
recipientsLimit
optional
integer
Maximum recipients items in one page. Defaults to 100.

maximum: 100 · minimum: 1 · default: 100

Returns

200

Successful operation.

JSON

success
boolean
required
data
object
required
- 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.
}
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.
RESOURCE_NOT_FOUND: The requested resource does not exist in this organization.

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
}