API referenceSegments

Segments

An audience. A segment is a filter over your contacts, a list of contacts added by hand, or both — and it is what a broadcast is sent to.

The filter

A filter is a tree of all, any and not groups over conditions. A condition is either { field, op, value } or { topic, subscription }. Groups nest three deep and a filter holds at most twenty conditions.

{
  "any": [
    {
      "all": [
        {
          "field": "properties.plan",
          "op": "eq",
          "value": "trial"
        },
        {
          "field": "created_at",
          "op": "gte",
          "value": "2026-09-01T00:00:00Z"
        }
      ]
    },
    {
      "topic": "b6d24b8e-af0b-4c3c-be0c-359bbd97381e",
      "subscription": "opt_in"
    }
  ]
}

Filter fields and the operators each accepts
Field	Type	Operators
`email`	string	`eq`, `neq`, `contains`, `in`
`first_name`	string	`eq`, `neq`, `contains`, `exists`, `in`
`last_name`	string	`eq`, `neq`, `contains`, `exists`, `in`
`unsubscribed`	boolean	`eq`
`created_at`	date	`gt`, `gte`, `lt`, `lte`
`properties.<key>`	the property's type	Strings as `first_name`; numbers `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `in`, `exists`

The filter is checked when the segment is created: a property that is not declared, or an operator that does not suit its type, is 422 validation_error with one entry in errors[] per condition.
A filter is never changed. Rename a segment freely; for a different audience, create a new one, so a sent broadcast keeps naming the audience it went to.

Membership

A contact is in a segment if the filter matches it or it was added explicitly. Membership is evaluated when it is read and when a broadcast is sent — never stored — so a contact who starts matching is in from that moment, and one who stops matching is out, unless they were added by hand. Deleted contacts are never members.

Endpoints

Create a segment

POST /segments

Name an audience, optionally defined by a filter over your contacts.

Body

namestringRequired
Up to 200 characters, unique among live segments.
filterobject | null
{ all | any | not: [ … ] } over { field, op, value } and { topic, subscription } conditions. Omit it for a segment with explicit membership only.

Request

curl -X POST "https://api.rasket.com/segments" \
  -H "Authorization: Bearer $RASKET_API_KEY" \
  -H "User-Agent: acme-billing/1.0" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Trial accounts",
  "filter": {
    "all": [
      {
        "field": "properties.plan",
        "op": "eq",
        "value": "trial"
      },
      {
        "field": "created_at",
        "op": "gte",
        "value": "2026-09-01T00:00:00Z"
      }
    ]
  }
}'

const response = await fetch("https://api.rasket.com/segments", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.RASKET_API_KEY}`,
    "User-Agent": "acme-billing/1.0",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Trial accounts",
    filter: {
      all: [
        {
          field: "properties.plan",
          op: "eq",
          value: "trial"
        },
        {
          field: "created_at",
          op: "gte",
          value: "2026-09-01T00:00:00Z"
        }
      ]
    }
  }),
});

const { id } = await response.json();

import os

import requests

response = requests.post(
    "https://api.rasket.com/segments",
    headers={
        "Authorization": f"Bearer {os.environ['RASKET_API_KEY']}",
        "User-Agent": "acme-billing/1.0",
    },
    json={
    "name": "Trial accounts",
    "filter": {
      "all": [
        {
          "field": "properties.plan",
          "op": "eq",
          "value": "trial"
        },
        {
          "field": "created_at",
          "op": "gte",
          "value": "2026-09-01T00:00:00Z"
        }
      ]
    }
  },
)

id = response.json()["id"]

Response 201

{
  "object": "segment",
  "id": "78261eea-8f8b-4381-83c6-79fa7120f1cf"
}

The filter is checked against your contact properties when the segment is created: an undeclared property, or an operator that does not suit its type, is 422 validation_error with one errors[] entry per condition.
Membership is evaluated when it is read and when a broadcast is sent, never stored — a contact that starts matching is in the segment from that moment.

List segments

GET /segments

Every live segment, newest first.

Query parameters

limitinteger
How many items to return, 1–100. Defaults to 20.
afterstring
Return the page that follows this item ID. Mutually exclusive with before.
beforestring
Return the page that precedes this item ID. Mutually exclusive with after.

Request

curl -X GET "https://api.rasket.com/segments" \
  -H "Authorization: Bearer $RASKET_API_KEY" \
  -H "User-Agent: acme-billing/1.0"

const response = await fetch("https://api.rasket.com/segments", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.RASKET_API_KEY}`,
    "User-Agent": "acme-billing/1.0",
  },
});

const data = await response.json();

import os

import requests

response = requests.get(
    "https://api.rasket.com/segments",
    headers={
        "Authorization": f"Bearer {os.environ['RASKET_API_KEY']}",
        "User-Agent": "acme-billing/1.0",
    },
)

print(response.json())

Response 200

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "id": "78261eea-8f8b-4381-83c6-79fa7120f1cf",
      "name": "Trial accounts",
      "created_at": "2026-09-08T22:22:17.595Z"
    }
  ]
}

List items carry no filter; retrieve a segment for it.

Retrieve a segment

GET /segments/{segment}

One segment, with its filter.

Path parameters

segmentstringRequired
The segment's ID.

Request

curl -X GET "https://api.rasket.com/segments/78261eea-8f8b-4381-83c6-79fa7120f1cf" \
  -H "Authorization: Bearer $RASKET_API_KEY" \
  -H "User-Agent: acme-billing/1.0"

const response = await fetch("https://api.rasket.com/segments/78261eea-8f8b-4381-83c6-79fa7120f1cf", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.RASKET_API_KEY}`,
    "User-Agent": "acme-billing/1.0",
  },
});

const { id } = await response.json();

import os

import requests

response = requests.get(
    "https://api.rasket.com/segments/78261eea-8f8b-4381-83c6-79fa7120f1cf",
    headers={
        "Authorization": f"Bearer {os.environ['RASKET_API_KEY']}",
        "User-Agent": "acme-billing/1.0",
    },
)

id = response.json()["id"]

Response 200

{
  "object": "segment",
  "id": "78261eea-8f8b-4381-83c6-79fa7120f1cf",
  "name": "Trial accounts",
  "filter": {
    "all": [
      {
        "field": "properties.plan",
        "op": "eq",
        "value": "trial"
      },
      {
        "field": "created_at",
        "op": "gte",
        "value": "2026-09-01T00:00:00Z"
      }
    ]
  },
  "created_at": "2026-09-08T22:22:17.595Z"
}

filter is null for a segment with explicit membership only.

Rename a segment

PATCH /segments/{segment}

Change the name. The filter is fixed.

Path parameters

segmentstringRequired
The segment's ID.

Body

namestringRequired
The new name.

Request

curl -X PATCH "https://api.rasket.com/segments/78261eea-8f8b-4381-83c6-79fa7120f1cf" \
  -H "Authorization: Bearer $RASKET_API_KEY" \
  -H "User-Agent: acme-billing/1.0" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Trials, September"
}'

const response = await fetch("https://api.rasket.com/segments/78261eea-8f8b-4381-83c6-79fa7120f1cf", {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.RASKET_API_KEY}`,
    "User-Agent": "acme-billing/1.0",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Trials, September"
  }),
});

const { id } = await response.json();

import os

import requests

response = requests.patch(
    "https://api.rasket.com/segments/78261eea-8f8b-4381-83c6-79fa7120f1cf",
    headers={
        "Authorization": f"Bearer {os.environ['RASKET_API_KEY']}",
        "User-Agent": "acme-billing/1.0",
    },
    json={
    "name": "Trials, September"
  },
)

id = response.json()["id"]

Response 200

{
  "object": "segment",
  "id": "78261eea-8f8b-4381-83c6-79fa7120f1cf"
}

A filter in the body is 422 invalid_parameter rather than silently dropped. A different audience is a new segment, so that a sent broadcast keeps naming the audience it went to.

Delete a segment

DELETE /segments/{segment}

Retire the segment and free its name.

Path parameters

segmentstringRequired
The segment's ID.

Request

curl -X DELETE "https://api.rasket.com/segments/78261eea-8f8b-4381-83c6-79fa7120f1cf" \
  -H "Authorization: Bearer $RASKET_API_KEY" \
  -H "User-Agent: acme-billing/1.0"

const response = await fetch("https://api.rasket.com/segments/78261eea-8f8b-4381-83c6-79fa7120f1cf", {
  method: "DELETE",
  headers: {
    Authorization: `Bearer ${process.env.RASKET_API_KEY}`,
    "User-Agent": "acme-billing/1.0",
  },
});

const { id } = await response.json();

import os

import requests

response = requests.delete(
    "https://api.rasket.com/segments/78261eea-8f8b-4381-83c6-79fa7120f1cf",
    headers={
        "Authorization": f"Bearer {os.environ['RASKET_API_KEY']}",
        "User-Agent": "acme-billing/1.0",
    },
)

id = response.json()["id"]

Response 200

{
  "object": "segment",
  "id": "78261eea-8f8b-4381-83c6-79fa7120f1cf",
  "deleted": true
}

The segment is 404 from that moment. Past broadcasts that went to it keep their recipients; a draft that names it cannot be sent until it names another.

List a segment's contacts

GET /segments/{segment}/contacts

The members, evaluated now: the filter's matches plus explicit additions.

Path parameters

segmentstringRequired
The segment's ID.

Query parameters

limitinteger
How many items to return, 1–100. Defaults to 20.
afterstring
Return the page that follows this item ID. Mutually exclusive with before.
beforestring
Return the page that precedes this item ID. Mutually exclusive with after.

Request

curl -X GET "https://api.rasket.com/segments/78261eea-8f8b-4381-83c6-79fa7120f1cf/contacts" \
  -H "Authorization: Bearer $RASKET_API_KEY" \
  -H "User-Agent: acme-billing/1.0"

const response = await fetch("https://api.rasket.com/segments/78261eea-8f8b-4381-83c6-79fa7120f1cf/contacts", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.RASKET_API_KEY}`,
    "User-Agent": "acme-billing/1.0",
  },
});

const data = await response.json();

import os

import requests

response = requests.get(
    "https://api.rasket.com/segments/78261eea-8f8b-4381-83c6-79fa7120f1cf/contacts",
    headers={
        "Authorization": f"Bearer {os.environ['RASKET_API_KEY']}",
        "User-Agent": "acme-billing/1.0",
    },
)

print(response.json())

Response 200

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "id": "e169aa45-1ecf-4183-9955-b1499d5701d3",
      "email": "ronald.williams@example.com",
      "first_name": "Ronald",
      "last_name": "Williams",
      "created_at": "2026-09-08T22:22:17.595Z",
      "unsubscribed": false
    }
  ]
}

This is the audience a broadcast to the segment would resolve, before subscription, suppression and unsubscribe filtering. Deleted contacts are never listed.

Retrieve a segment's size

GET /segments/{segment}/metrics

How many contacts the segment resolves to right now.

Path parameters

segmentstringRequired
The segment's ID.

Request

curl -X GET "https://api.rasket.com/segments/78261eea-8f8b-4381-83c6-79fa7120f1cf/metrics" \
  -H "Authorization: Bearer $RASKET_API_KEY" \
  -H "User-Agent: acme-billing/1.0"

const response = await fetch("https://api.rasket.com/segments/78261eea-8f8b-4381-83c6-79fa7120f1cf/metrics", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.RASKET_API_KEY}`,
    "User-Agent": "acme-billing/1.0",
  },
});

const data = await response.json();

import os

import requests

response = requests.get(
    "https://api.rasket.com/segments/78261eea-8f8b-4381-83c6-79fa7120f1cf/metrics",
    headers={
        "Authorization": f"Bearer {os.environ['RASKET_API_KEY']}",
        "User-Agent": "acme-billing/1.0",
    },
)

print(response.json())

Response 200

{
  "object": "segment_metrics",
  "segment_id": "78261eea-8f8b-4381-83c6-79fa7120f1cf",
  "contacts": 1240,
  "subscribed": 1197,
  "unsubscribed": 43
}

One pass over the same membership /contacts lists, split on the global unsubscribe.

Preview a segment

POST /segments/preview

How many contacts a filter matches right now, without creating a segment.

Body

filterobjectRequired
A filter exactly as POST /segments takes it.

Request

curl -X POST "https://api.rasket.com/segments/preview" \
  -H "Authorization: Bearer $RASKET_API_KEY" \
  -H "User-Agent: acme-billing/1.0" \
  -H "Content-Type: application/json" \
  -d '{
  "filter": {
    "all": [
      {
        "field": "properties.plan",
        "op": "eq",
        "value": "trial"
      },
      {
        "field": "created_at",
        "op": "gte",
        "value": "2026-09-01T00:00:00Z"
      }
    ]
  }
}'

const response = await fetch("https://api.rasket.com/segments/preview", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.RASKET_API_KEY}`,
    "User-Agent": "acme-billing/1.0",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    filter: {
      all: [
        {
          field: "properties.plan",
          op: "eq",
          value: "trial"
        },
        {
          field: "created_at",
          op: "gte",
          value: "2026-09-01T00:00:00Z"
        }
      ]
    }
  }),
});

const data = await response.json();

import os

import requests

response = requests.post(
    "https://api.rasket.com/segments/preview",
    headers={
        "Authorization": f"Bearer {os.environ['RASKET_API_KEY']}",
        "User-Agent": "acme-billing/1.0",
    },
    json={
    "filter": {
      "all": [
        {
          "field": "properties.plan",
          "op": "eq",
          "value": "trial"
        },
        {
          "field": "created_at",
          "op": "gte",
          "value": "2026-09-01T00:00:00Z"
        }
      ]
    }
  },
)

print(response.json())

Response 200

{
  "object": "segment_preview",
  "contacts": 1284
}

Nothing is stored. A filter POST /segments would refuse is 422 validation_error here, with the same errors[] paths.