List Campaigns
ReferenceUpdated June 14, 2026
List Campaigns
List campaigns in the workspace associated with your API key. Use this to let users (or agents) pick a campaign by name or ID before calling generate or generate-batch.
List campaigns
GET /api/v1/campaigns · scope campaigns:read
Returns campaigns in the API key's workspace (paginated).
Headers
| Header | Required | Description |
|---|---|---|
Authorization | Yes | Bearer <API_KEY> |
or X-API-Key | Yes | <API_KEY> |
Query parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
q | string | No | Filter by campaign name (case-insensitive substring). |
name | string | No | Same as q. |
limit | number | No | Max results (default 50, max 100). |
offset | number | No | Pagination offset (default 0). |
Example request
curl -X GET "https://app.machfive.io/api/v1/campaigns?q=Q1" \
-H "Authorization: Bearer YOUR_API_KEY"Response (200 OK)
{
"campaigns": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Q1 Outbound",
"created_at": "2025-01-15T12:00:00.000Z"
}
],
"has_more": false,
"total": 1
}| Field | Type | Description |
|---|---|---|
campaigns | array | List of campaigns. |
campaigns[].id | string (UUID) | Campaign ID; use in generate and generate-batch. |
campaigns[].name | string | Display name (project_name). |
campaigns[].created_at | string (ISO 8601) | Creation time. |
has_more | boolean | Whether more results exist beyond this page. |
total | number | Total campaigns matching the query. |
Error responses
| Status | Error | Description |
|---|---|---|
| 401 | UNAUTHORIZED | Missing or invalid API key. |
| 500 | INTERNAL_ERROR | Server error listing campaigns. |