# Broadcasts API

> Bulk sends to contacts on one account (Messenger / Instagram within the 24 h window or with HUMAN_AGENT, X, Bluesky…), rate limited per channel with per-recipient delivery status. Each recipient is one message.

Base URL: `https://api.socialit.com/v1`. Authenticate with `Authorization: Bearer <API key or OAuth token>`.

## List broadcasts

`GET /broadcasts`

Access: `read` · MCP tool: `list-broadcasts` · Zernio: `GET /v1/broadcasts`

### Query parameters

- `page` (integer; ≥ 1): Page number
- `limit` (integer; 1–100): Items per page (max 100)
- `sort` (string; one of created_at, scheduled_at, name)
- `order` (string; one of asc, desc)
- `match` (string; one of all, or): Combine filters with AND (default) or OR
- `profile_id` (string)
- `account_id` (string)
- `status` (string)
- `platform` (string)

```bash
curl "https://api.socialit.com/v1/broadcasts" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "object": "broadcast",
      "id": "string",
      "profile_id": "string",
      "account_id": "string",
      "account_name": "string",
      "platform": "string",
      "name": "string",
      "description": "string",
      "status": "draft",
      "message": {
        "text": "string",
        "attachments": [
          {
            "type": null,
            "url": null,
            "filename": null
          }
        ],
        "message_tag": "string"
      },
      "segment_filters": {
        "tags": [
          "string"
        ],
        "tags_match": "string",
        "exclude_tags": [
          "string"
        ],
        "is_subscribed": true,
        "custom_fields": {}
      },
      "message_preview": "string",
      "rate_limit_per_minute": 1,
      "scheduled_at": "2026-10-13T09:00:00.000Z",
      "started_at": "2026-10-13T09:00:00.000Z",
      "completed_at": "2026-10-13T09:00:00.000Z",
      "recipient_count": 1,
      "pending_count": 1,
      "sent_count": 1,
      "delivered_count": 1,
      "read_count": 1,
      "failed_count": 1,
      "skipped_count": 1,
      "last_error": "string",
      "created_at": "2026-10-13T09:00:00.000Z",
      "updated_at": "2026-10-13T09:00:00.000Z"
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com"
}
```

## Create a broadcast draft

`POST /broadcasts`

segment_filters select recipients by tags, subscription and custom fields.

Access: `write` · MCP tool: `create-broadcast` · Zernio: `POST /v1/broadcasts`

### Headers

- `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours.

### Body

- `profile_id` (string)
- `account_id` (string; required)
- `platform` (string; one of instagram, facebook, x, bluesky, reddit, discord, mastodon, tiktok, twitter)
- `name` (string; required; 1–200 characters)
- `description` (string | null; ≤ 2000 characters)
- `message` (object)
  - `message.text` (string | null; ≤ 4096 characters)
  - `message.attachments` (array of object; ≤ 10 items)
    - `message.attachments[].type` (string; one of image, video, audio, file)
    - `message.attachments[].url` (string; required; 1–2048 characters)
    - `message.attachments[].filename` (string; ≤ 255 characters)
  - `message.message_tag` (string | null; one of HUMAN_AGENT, CONFIRMED_EVENT_UPDATE, POST_PURCHASE_UPDATE, ACCOUNT_UPDATE)
- `segment_filters` (object | null)
  - `segment_filters.tags` (array of string; ≤ 100 items)
  - `segment_filters.tags_match` (string; one of any, all)
  - `segment_filters.exclude_tags` (array of string; ≤ 100 items)
  - `segment_filters.is_subscribed` (boolean)
  - `segment_filters.custom_fields` (object)
- `rate_limit_per_minute` (integer | null; 1–6000)

```bash
curl -X POST "https://api.socialit.com/v1/broadcasts" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "profile_id": "string",
    "account_id": "string",
    "platform": "instagram",
    "name": "string",
    "description": "string"
  }'
```

Response 201:

```json
{
  "object": "broadcast",
  "id": "string",
  "profile_id": "string",
  "account_id": "string",
  "account_name": "string",
  "platform": "string",
  "name": "string",
  "description": "string",
  "status": "draft",
  "message": {
    "text": "string",
    "attachments": [
      {
        "type": "string",
        "url": "https://example.com",
        "filename": "string"
      }
    ],
    "message_tag": "string"
  },
  "segment_filters": {
    "tags": [
      "string"
    ],
    "tags_match": "string",
    "exclude_tags": [
      "string"
    ],
    "is_subscribed": true,
    "custom_fields": {}
  },
  "message_preview": "string",
  "rate_limit_per_minute": 1,
  "scheduled_at": "2026-10-13T09:00:00.000Z",
  "started_at": "2026-10-13T09:00:00.000Z",
  "completed_at": "2026-10-13T09:00:00.000Z",
  "recipient_count": 1,
  "pending_count": 1,
  "sent_count": 1,
  "delivered_count": 1,
  "read_count": 1,
  "failed_count": 1,
  "skipped_count": 1,
  "last_error": "string",
  "created_at": "2026-10-13T09:00:00.000Z",
  "updated_at": "2026-10-13T09:00:00.000Z"
}
```

## Preview a broadcast audience

`POST /broadcasts/audience-preview`

Count (and sample) the contacts a segment reaches on an account.

Access: `read` · MCP tool: `preview-broadcast-audience`

### Body

- `profile_id` (string)
- `account_id` (string; required)
- `segment_filters` (object | null)
  - `segment_filters.tags` (array of string; ≤ 100 items)
  - `segment_filters.tags_match` (string; one of any, all)
  - `segment_filters.exclude_tags` (array of string; ≤ 100 items)
  - `segment_filters.is_subscribed` (boolean)
  - `segment_filters.custom_fields` (object)

```bash
curl -X POST "https://api.socialit.com/v1/broadcasts/audience-preview" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "profile_id": "string",
    "account_id": "string",
    "segment_filters": {
      "tags": [
        "string"
      ],
      "tags_match": "any"
    }
  }'
```

Response 200:

```json
{
  "object": "audience_preview",
  "count": 1,
  "sample": [
    {
      "contact_id": "string",
      "name": "string",
      "platform_identifier": "string"
    }
  ]
}
```

## Get a broadcast

`GET /broadcasts/{id}`

Access: `read` · MCP tool: `get-broadcast` · Zernio: `GET /v1/broadcasts/{broadcastId}`

### Path parameters

- `id` (string; required; 1–80 characters): broadcast id (brd_…)

```bash
curl "https://api.socialit.com/v1/broadcasts/brd_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "broadcast",
  "id": "string",
  "profile_id": "string",
  "account_id": "string",
  "account_name": "string",
  "platform": "string",
  "name": "string",
  "description": "string",
  "status": "draft",
  "message": {
    "text": "string",
    "attachments": [
      {
        "type": "string",
        "url": "https://example.com",
        "filename": "string"
      }
    ],
    "message_tag": "string"
  },
  "segment_filters": {
    "tags": [
      "string"
    ],
    "tags_match": "string",
    "exclude_tags": [
      "string"
    ],
    "is_subscribed": true,
    "custom_fields": {}
  },
  "message_preview": "string",
  "rate_limit_per_minute": 1,
  "scheduled_at": "2026-10-13T09:00:00.000Z",
  "started_at": "2026-10-13T09:00:00.000Z",
  "completed_at": "2026-10-13T09:00:00.000Z",
  "recipient_count": 1,
  "pending_count": 1,
  "sent_count": 1,
  "delivered_count": 1,
  "read_count": 1,
  "failed_count": 1,
  "skipped_count": 1,
  "last_error": "string",
  "created_at": "2026-10-13T09:00:00.000Z",
  "updated_at": "2026-10-13T09:00:00.000Z"
}
```

## Update a broadcast

`PATCH /broadcasts/{id}`

Only while draft or scheduled (409 broadcast_not_editable).

Access: `write` · MCP tool: `update-broadcast` · Zernio: `PATCH /v1/broadcasts/{broadcastId}`

### Path parameters

- `id` (string; required; 1–80 characters): broadcast id (brd_…)

### Body

- `name` (string; 1–200 characters)
- `description` (string | null; ≤ 2000 characters)
- `message` (object)
  - `message.text` (string | null; ≤ 4096 characters)
  - `message.attachments` (array of object; ≤ 10 items)
    - `message.attachments[].type` (string; one of image, video, audio, file)
    - `message.attachments[].url` (string; required; 1–2048 characters)
    - `message.attachments[].filename` (string; ≤ 255 characters)
  - `message.message_tag` (string | null; one of HUMAN_AGENT, CONFIRMED_EVENT_UPDATE, POST_PURCHASE_UPDATE, ACCOUNT_UPDATE)
- `segment_filters` (object | null)
  - `segment_filters.tags` (array of string; ≤ 100 items)
  - `segment_filters.tags_match` (string; one of any, all)
  - `segment_filters.exclude_tags` (array of string; ≤ 100 items)
  - `segment_filters.is_subscribed` (boolean)
  - `segment_filters.custom_fields` (object)
- `rate_limit_per_minute` (integer | null; 1–6000)

```bash
curl -X PATCH "https://api.socialit.com/v1/broadcasts/brd_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "string",
    "description": "string",
    "message": {
      "text": "string",
      "attachments": [
        {
          "type": "image",
          "url": "https://example.com"
        }
      ]
    },
    "segment_filters": {
      "tags": [
        "string"
      ],
      "tags_match": "any"
    },
    "rate_limit_per_minute": 1
  }'
```

Response 200:

```json
{
  "object": "broadcast",
  "id": "string",
  "profile_id": "string",
  "account_id": "string",
  "account_name": "string",
  "platform": "string",
  "name": "string",
  "description": "string",
  "status": "draft",
  "message": {
    "text": "string",
    "attachments": [
      {
        "type": "string",
        "url": "https://example.com",
        "filename": "string"
      }
    ],
    "message_tag": "string"
  },
  "segment_filters": {
    "tags": [
      "string"
    ],
    "tags_match": "string",
    "exclude_tags": [
      "string"
    ],
    "is_subscribed": true,
    "custom_fields": {}
  },
  "message_preview": "string",
  "rate_limit_per_minute": 1,
  "scheduled_at": "2026-10-13T09:00:00.000Z",
  "started_at": "2026-10-13T09:00:00.000Z",
  "completed_at": "2026-10-13T09:00:00.000Z",
  "recipient_count": 1,
  "pending_count": 1,
  "sent_count": 1,
  "delivered_count": 1,
  "read_count": 1,
  "failed_count": 1,
  "skipped_count": 1,
  "last_error": "string",
  "created_at": "2026-10-13T09:00:00.000Z",
  "updated_at": "2026-10-13T09:00:00.000Z"
}
```

## Delete a broadcast

`DELETE /broadcasts/{id}`

Not while sending (cancel first).

Access: `write` · MCP tool: `delete-broadcast` · Zernio: `DELETE /v1/broadcasts/{broadcastId}`

### Path parameters

- `id` (string; required; 1–80 characters): broadcast id (brd_…)

```bash
curl -X DELETE "https://api.socialit.com/v1/broadcasts/brd_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "broadcast",
  "id": "string",
  "deleted": true
}
```

## Send a broadcast now

`POST /broadcasts/{id}/send`

Resolves the segment when no recipients were added (422 no_recipients when nothing matches) and starts sending in rate-limited batches.

Access: `write` · MCP tool: `send-broadcast` · Zernio: `POST /v1/broadcasts/{broadcastId}/send`

### Path parameters

- `id` (string; required; 1–80 characters): broadcast id (brd_…)

### Headers

- `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours.

```bash
curl -X POST "https://api.socialit.com/v1/broadcasts/brd_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/send" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
```

Response 200:

```json
{
  "object": "broadcast",
  "id": "string",
  "profile_id": "string",
  "account_id": "string",
  "account_name": "string",
  "platform": "string",
  "name": "string",
  "description": "string",
  "status": "draft",
  "message": {
    "text": "string",
    "attachments": [
      {
        "type": "string",
        "url": "https://example.com",
        "filename": "string"
      }
    ],
    "message_tag": "string"
  },
  "segment_filters": {
    "tags": [
      "string"
    ],
    "tags_match": "string",
    "exclude_tags": [
      "string"
    ],
    "is_subscribed": true,
    "custom_fields": {}
  },
  "message_preview": "string",
  "rate_limit_per_minute": 1,
  "scheduled_at": "2026-10-13T09:00:00.000Z",
  "started_at": "2026-10-13T09:00:00.000Z",
  "completed_at": "2026-10-13T09:00:00.000Z",
  "recipient_count": 1,
  "pending_count": 1,
  "sent_count": 1,
  "delivered_count": 1,
  "read_count": 1,
  "failed_count": 1,
  "skipped_count": 1,
  "last_error": "string",
  "created_at": "2026-10-13T09:00:00.000Z",
  "updated_at": "2026-10-13T09:00:00.000Z"
}
```

## Schedule a broadcast

`POST /broadcasts/{id}/schedule`

Access: `write` · MCP tool: `schedule-broadcast` · Zernio: `POST /v1/broadcasts/{broadcastId}/schedule`

### Path parameters

- `id` (string; required; 1–80 characters): broadcast id (brd_…)

### Headers

- `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours.

### Body

- `scheduled_at` (string (date-time); required)

```bash
curl -X POST "https://api.socialit.com/v1/broadcasts/brd_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/schedule" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "scheduled_at": "2026-10-13T09:00:00.000Z"
  }'
```

Response 200:

```json
{
  "object": "broadcast",
  "id": "string",
  "profile_id": "string",
  "account_id": "string",
  "account_name": "string",
  "platform": "string",
  "name": "string",
  "description": "string",
  "status": "draft",
  "message": {
    "text": "string",
    "attachments": [
      {
        "type": "string",
        "url": "https://example.com",
        "filename": "string"
      }
    ],
    "message_tag": "string"
  },
  "segment_filters": {
    "tags": [
      "string"
    ],
    "tags_match": "string",
    "exclude_tags": [
      "string"
    ],
    "is_subscribed": true,
    "custom_fields": {}
  },
  "message_preview": "string",
  "rate_limit_per_minute": 1,
  "scheduled_at": "2026-10-13T09:00:00.000Z",
  "started_at": "2026-10-13T09:00:00.000Z",
  "completed_at": "2026-10-13T09:00:00.000Z",
  "recipient_count": 1,
  "pending_count": 1,
  "sent_count": 1,
  "delivered_count": 1,
  "read_count": 1,
  "failed_count": 1,
  "skipped_count": 1,
  "last_error": "string",
  "created_at": "2026-10-13T09:00:00.000Z",
  "updated_at": "2026-10-13T09:00:00.000Z"
}
```

## Cancel a broadcast

`POST /broadcasts/{id}/cancel`

Pending recipients become skipped.

Access: `write` · MCP tool: `cancel-broadcast` · Zernio: `POST /v1/broadcasts/{broadcastId}/cancel`

### Path parameters

- `id` (string; required; 1–80 characters): broadcast id (brd_…)

```bash
curl -X POST "https://api.socialit.com/v1/broadcasts/brd_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/cancel" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "broadcast",
  "id": "string",
  "profile_id": "string",
  "account_id": "string",
  "account_name": "string",
  "platform": "string",
  "name": "string",
  "description": "string",
  "status": "draft",
  "message": {
    "text": "string",
    "attachments": [
      {
        "type": "string",
        "url": "https://example.com",
        "filename": "string"
      }
    ],
    "message_tag": "string"
  },
  "segment_filters": {
    "tags": [
      "string"
    ],
    "tags_match": "string",
    "exclude_tags": [
      "string"
    ],
    "is_subscribed": true,
    "custom_fields": {}
  },
  "message_preview": "string",
  "rate_limit_per_minute": 1,
  "scheduled_at": "2026-10-13T09:00:00.000Z",
  "started_at": "2026-10-13T09:00:00.000Z",
  "completed_at": "2026-10-13T09:00:00.000Z",
  "recipient_count": 1,
  "pending_count": 1,
  "sent_count": 1,
  "delivered_count": 1,
  "read_count": 1,
  "failed_count": 1,
  "skipped_count": 1,
  "last_error": "string",
  "created_at": "2026-10-13T09:00:00.000Z",
  "updated_at": "2026-10-13T09:00:00.000Z"
}
```

## List broadcast recipients

`GET /broadcasts/{id}/recipients`

Access: `read` · MCP tool: `list-broadcast-recipients` · Zernio: `GET /v1/broadcasts/{broadcastId}/recipients`

### Path parameters

- `id` (string; required; 1–80 characters): broadcast id (brd_…)

### Query parameters

- `page` (integer; ≥ 1): Page number
- `limit` (integer; 1–100): Items per page (max 100)
- `sort` (string; one of created_at, sent_at)
- `order` (string; one of asc, desc)
- `match` (string; one of all, or): Combine filters with AND (default) or OR
- `status` (string)
- `contact_id` (string)

```bash
curl "https://api.socialit.com/v1/broadcasts/brd_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/recipients" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "object": "broadcast_recipient",
      "id": "string",
      "broadcast_id": "string",
      "contact_id": "string",
      "channel_id": "string",
      "contact_name": "string",
      "platform_identifier": "string",
      "status": "pending",
      "message_id": "string",
      "error": "string",
      "error_code": "string",
      "sent_at": "2026-10-13T09:00:00.000Z",
      "delivered_at": "2026-10-13T09:00:00.000Z",
      "read_at": "2026-10-13T09:00:00.000Z",
      "created_at": "2026-10-13T09:00:00.000Z"
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com"
}
```

## Add broadcast recipients

`POST /broadcasts/{id}/recipients`

By contact_ids and/or use_segment. Contacts without a subscribed channel on the account are skipped.

Access: `write` · MCP tool: `add-broadcast-recipients` · Zernio: `POST /v1/broadcasts/{broadcastId}/recipients`

### Path parameters

- `id` (string; required; 1–80 characters): broadcast id (brd_…)

### Headers

- `Idempotency-Key` (string; ≤ 255 characters): Unique key (for example a UUID) that makes retries safe: a repeated request with the same key and body returns the first response (Idempotent-Replayed: true) for 24 hours.

### Body

- `contact_ids` (array of string; ≤ 10000 items)
- `use_segment` (boolean)

```bash
curl -X POST "https://api.socialit.com/v1/broadcasts/brd_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd/recipients" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_ids": [
      "string"
    ],
    "use_segment": true
  }'
```

Response 200:

```json
{
  "object": "broadcast_recipients_result",
  "added": 1,
  "skipped": 1,
  "recipient_count": 1
}
```


---

Source: https://socialit.com/docs/api-reference/broadcasts/
