Reading Activities

The most common integration pattern is reading activities assigned to your commerces. Use the activities endpoints to list, filter, and inspect activity details.

Listing Activities

Use GET /api/activities with filters to find activities. All list responses are paginated.

Available Filters

Parameter	Type	Description
`status`	string	Filter by status: `READY`, `UNRESOLVED`, `DISPATCHED`, `COMPLETED`, `CANCELED`, `FAILED`
`type`	string	Filter by type: `TASK`, `MESSAGE`
`channel`	string	Filter by channel: `SALESMAN`, `CALLCENTER`, `WHATSAPP`, `EMAIL`, `SMS`, `PUSH`
`commerce_id`	UUID	Filter by specific commerce
`scheduled_from`	ISO 8601	Activities scheduled after this date
`scheduled_to`	ISO 8601	Activities scheduled before this date
`search`	string	Free text search
`page`	number	Page number (default: 1)
`per_page`	number	Items per page (default: 25, max: 100)

Example: List READY tasks

curl "https://api.reten.ai/api/activities?status=READY&type=TASK&page=1&per_page=10" \
  -H "Authorization: Bearer <token>" \
  -H "x-tenant-id: <tenant-id>"

import axios from 'axios';

const response = await axios.get(
  'https://api.reten.ai/api/activities',
  {
    params: {
      status: 'READY',
      type: 'TASK',
      page: 1,
      per_page: 10,
    },
    headers: {
      Authorization: 'Bearer <token>',
      'x-tenant-id': '<tenant-id>',
    },
  }
);

const { data: activities, meta } = response.data;

Response

{
  "data": [
    {
      "id": "ee0e8400-e29b-41d4-a716-446655440000",
      "type": "TASK",
      "channel": "SALESMAN",
      "status": "READY",
      "scheduledAt": "2025-01-16T09:00:00.000Z",
      "commerceAssignment": {
        "commerceId": "880e8400-...",
        "commerce": {
          "name": "Main Street Store"
        }
      }
    }
  ],
  "meta": {
    "page": 1,
    "limit": 10,
    "total": 42,
    "totalPages": 5
  }
}

Getting Activity Details

Use GET /api/activities/:id to retrieve a single activity with its commerce assignment and full details.

Example

curl https://api.reten.ai/api/activities/ee0e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer <token>" \
  -H "x-tenant-id: <tenant-id>"

const response = await axios.get(
  'https://api.reten.ai/api/activities/ee0e8400-e29b-41d4-a716-446655440000',
  {
    headers: {
      Authorization: 'Bearer <token>',
      'x-tenant-id': '<tenant-id>',
    },
  }
);

const activity = response.data;

Checking Status Events

Every status transition creates an audit trail entry. Use GET /api/activities/:id/status-events to view the complete history.

Example

curl https://api.reten.ai/api/activities/ee0e8400-e29b-41d4-a716-446655440000/status-events \
  -H "Authorization: Bearer <token>" \
  -H "x-tenant-id: <tenant-id>"

const response = await axios.get(
  `https://api.reten.ai/api/activities/${activityId}/status-events`,
  {
    headers: {
      Authorization: 'Bearer <token>',
      'x-tenant-id': '<tenant-id>',
    },
  }
);

const events = response.data;
// Each event has: eventType, fromStatus, toStatus, occurredAt

Response

[
  {
    "id": "ff0e8400-...",
    "eventType": "CREATED",
    "fromStatus": null,
    "toStatus": "READY",
    "occurredAt": "2025-01-15T10:30:00.000Z"
  },
  {
    "id": "ff1e8400-...",
    "eventType": "DISPATCH_SUCCESS",
    "fromStatus": "READY",
    "toStatus": "DISPATCHED",
    "occurredAt": "2025-01-15T10:31:00.000Z"
  }
]

Event Types

Event	Description
`CREATED`	Activity created with READY status
`CREATION_FAILED`	Activity creation failed
`DISPATCH_ATTEMPT`	Dispatch attempt started
`DISPATCH_SUCCESS`	Successfully dispatched to provider
`DISPATCH_FAILED`	Dispatch attempt failed
`COMPLETED`	Activity execution completed
`CANCELED`	Activity manually canceled
`FAILED`	Activity execution failed
`RESOLUTION_FAILED`	Target user or attribute resolution failed (activity → UNRESOLVED)
`RESOLUTION_RETRY_SUCCESS`	Retry resolved all pending targets/attributes (activity → READY)
`RESOLUTION_RETRY_FAILED`	Retry did not resolve all pending targets/attributes

Viewing Activity Attributes

Activities can have key-value attributes attached during creation. Use GET /api/activities/:id/attributes to retrieve them.

Example

curl https://api.reten.ai/api/activities/ee0e8400-e29b-41d4-a716-446655440000/attributes \
  -H "Authorization: Bearer <token>" \
  -H "x-tenant-id: <tenant-id>"

const response = await axios.get(
  `https://api.reten.ai/api/activities/${activityId}/attributes`,
  {
    headers: {
      Authorization: 'Bearer <token>',
      'x-tenant-id': '<tenant-id>',
    },
  }
);

const attributes = response.data;

Required Permission

All read operations require the VIEW_ACTIVITIES permission, available to SUPER_ADMIN, ADMIN, FDE, and VIEWER roles.