Skip to main content

Querying and Filtering

The Flow API supports powerful querying and filtering capabilities for list endpoints.

Basic Filtering​

Use query parameters to filter results:

# Filter by status
GET /v1/posts?filter[status]=queued

# Filter by channel
GET /v1/posts?filter[channelId]=channel_123

# Multiple filters
GET /v1/posts?filter[status]=queued&filter[channelId]=channel_123

Advanced Filtering​

Use operators for more complex queries:

Comparison Operators​

  • eq - Equals
  • ne - Not equals
  • gt - Greater than
  • gte - Greater than or equal
  • lt - Less than
  • lte - Less than or equal
  • in - In array
  • contains - Contains substring (strings only)

Examples​

# Posts scheduled after a date
GET /v1/posts?filter[scheduledFor][gte]=1703000000000

# Posts in multiple channels
GET /v1/posts?filter[channelId][in]=channel_1,channel_2,channel_3

# Posts with content containing "hello"
GET /v1/posts?filter[content][contains]=hello

# Posts created before a date
GET /v1/posts?filter[createdAt][lt]=1703000000000

Sorting​

Sort results using the sort parameter:

# Sort by scheduled date (descending)
GET /v1/posts?sort=-scheduledFor

# Sort by creation date (ascending)
GET /v1/posts?sort=createdAt

# Multiple sort fields (comma-separated)
GET /v1/posts?sort=-scheduledFor,createdAt

Prefix with - for descending order, no prefix for ascending.

Pagination​

Control pagination with page and perPage:

# Get page 2 with 50 items per page
GET /v1/posts?page=2&perPage=50

Default values:

  • page: 1
  • perPage: 20
  • Maximum perPage: 100

Combining Filters​

You can combine multiple filters:

GET /v1/posts?filter[status]=queued&filter[channelId]=channel_123&filter[scheduledFor][gte]=1703000000000&sort=-scheduledFor&page=1&perPage=50

Filterable Fields​

Posts​

  • status - Post status (queued, flowing, done, blocked)
  • channelId - Channel ID
  • scheduledFor - Scheduled timestamp
  • createdAt - Creation timestamp
  • content - Post content (supports contains)

Channels​

  • name - Channel name (supports contains)
  • createdAt - Creation timestamp

Examples​

Get Queued Posts for a Channel​

GET /v1/posts?filter[status]=queued&filter[channelId]=channel_123

Get Posts Scheduled for Today​

const today = new Date();
today.setHours(0, 0, 0, 0);
const tomorrow = new Date(today);
tomorrow.setDate(tomorrow.getDate() + 1);

const posts = await flow.posts.list({
  filter: {
    scheduledFor: {
      gte: today.getTime(),
      lt: tomorrow.getTime(),
    },
  },
});

Search Posts by Content​

GET /v1/posts?filter[content][contains]=product%20launch

Get Recent Posts​

GET /v1/posts?sort=-createdAt&perPage=10

Response Format​

Filtered responses include pagination metadata:

{
  "data": [...],
  "pagination": {
    "page": 1,
    "perPage": 20,
    "total": 150,
    "totalPages": 8
  }
}