Skip to main content

Advanced Querying

The Flow API supports advanced filtering and querying across all list endpoints. This guide covers the query syntax and available operators.

Filter Syntax​

Filters use the filter[field] or filter[field][operator] syntax:

GET /v1/posts?filter[status]=queued
GET /v1/posts?filter[status][ne]=done
GET /v1/posts?filter[scheduledFor][gte]=1703123456000

Supported Operators​

OperatorDescriptionExample
eqEquals (default)?filter[status]=queued
neNot equals?filter[status][ne]=done
gtGreater than?filter[scheduledFor][gt]=1703123456000
gteGreater than or equal?filter[scheduledFor][gte]=1703123456000
ltLess than?filter[scheduledFor][lt]=1703123456000
lteLess than or equal?filter[scheduledFor][lte]=1703123456000
inIn array?filter[channelId][in]=id1,id2,id3
containsString contains?filter[content][contains]=hello

Examples​

Posts​

# Get all queued posts
GET /v1/posts?filter[status]=queued

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

# Get posts from specific channels
GET /v1/posts?filter[channelId][in]=channel1,channel2,channel3

# Get posts containing specific text
GET /v1/posts?filter[content][contains]=announcement

# Combine multiple filters
GET /v1/posts?filter[status]=queued&filter[channelId]=channel123&filter[scheduledFor][gte]=1703123456000

Channels​

# Get channels created after a date
GET /v1/channels?filter[createdAt][gte]=1703123456000

# Get channels with specific name
GET /v1/channels?filter[name][contains]=marketing

Combining Filters​

Multiple filters are combined with AND logic:

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

This returns posts that are:

  • Status equals "queued" AND
  • Channel ID equals "channel123"

Date/Time Filtering​

For timestamp fields (scheduledFor, createdAt), you can use:

  • Unix timestamp (milliseconds): ?filter[scheduledFor][gte]=1703123456000
  • ISO 8601 string: ?filter[scheduledFor][gte]=2024-12-25T10:00:00Z

Both formats are automatically parsed.

Array Filtering (IN)​

Use the in operator to match multiple values:

GET /v1/posts?filter[channelId][in]=channel1,channel2,channel3

Values are comma-separated. Empty values are ignored.

String Contains​

Use the contains operator for partial string matching:

GET /v1/posts?filter[content][contains]=announcement

This matches posts where the content contains "announcement" (case-sensitive in SQLite).

Sorting​

Combine filtering with sorting:

GET /v1/posts?filter[status]=queued&sort=-scheduledFor

Sort syntax:

  • sort=field - Ascending
  • sort=-field - Descending

Available sort fields:

  • scheduledFor (default)
  • createdAt
  • status

Pagination​

Filters work with pagination:

GET /v1/posts?filter[status]=queued&page=1&per_page=20

Field Reference​

Posts​

FieldTypeOperators
statusstringeq, ne, in
channelIdstringeq, ne, in
scheduledFornumber (timestamp)eq, ne, gt, gte, lt, lte
createdAtnumber (timestamp)eq, ne, gt, gte, lt, lte
contentstringcontains

Channels​

FieldTypeOperators
namestringcontains
createdAtnumber (timestamp)eq, ne, gt, gte, lt, lte

Limitations​

  1. Case sensitivity: String comparisons are case-sensitive (SQLite limitation)
  2. Performance: Complex filters may be slower on large datasets
  3. Field support: Not all fields support all operators (see field reference above)

Best Practices​

  1. Use specific filters - Narrow down results before pagination
  2. Combine with pagination - Always paginate large result sets
  3. Index fields - Filter on indexed fields for better performance
  4. Limit filter complexity - Too many filters can slow down queries

SDK Support​

The Flow SDKs support filtering:

TypeScript SDK​

// Filtering is built into list methods
const posts = await flow.posts.list({
  status: 'queued',
  channelId: 'channel_123',
});

Python SDK​

# Filtering via query parameters
posts = flow.posts.list(
    status='queued',
    channel_id='channel_123'
)

Examples​

Get posts scheduled for today​

# Get current timestamp
NOW=$(date +%s)000  # Convert to milliseconds
TODAY_START=$((NOW - (NOW % 86400000)))  # Start of day
TODAY_END=$((TODAY_START + 86400000))    # End of day

GET /v1/posts?filter[scheduledFor][gte]=${TODAY_START}&filter[scheduledFor][lt]=${TODAY_END}

Get posts from multiple channels​

GET /v1/posts?filter[channelId][in]=channel1,channel2,channel3

Get queued posts scheduled in the future​

NOW=$(date +%s)000
GET /v1/posts?filter[status]=queued&filter[scheduledFor][gt]=${NOW}

Support​