Filtering Data

Our APIs support filtering and searching to help you retrieve only the data you need. The filtering mechanism uses a query parameter named filters, which takes a specially formatted query string. Currently, this feature is available for a limited set of APIs and attributes.

Filter Query Format

The filters query follows a structured format similar to SQL queries but optimized for API requests. Below are the rules for constructing a valid filter query:

1. Attribute and Operator Syntax

Each filter condition consists of an attribute name, followed by a period (.) and an operator.

Example:

account_id.eq=12345

2. Supported Operators

We currently support the following operators:

eq (equals) – Matches values exactly.
Example: account_id.eq=12345 retrieves records where account_id is 12345.
not (not equals) – Excludes values that match exactly.
Example: account_id.not=67890 retrieves records where account_id is not 67890.

3. Combining Multiple Attributes in a query

Use && to combine multiple conditions with a logical AND. Example:

account_id.eq=12345&&format.eq=json

Filters results where account_id is 12345 AND format is json.

4. Multiple Values in a query

Use comma-separated values [a,b,c] to apply a logical OR within an attribute.

Example:

account_id.eq=[12345,67890,54321]

Retrieves records where account_id is 12345 OR 67890 OR 54321.

Invalid formats: Ensure values do not contain empty entries, spaces, or extra commas.

[12345, ,67890]   ❌ Invalid
[, , 12345]       ❌ Invalid
[12345,,]         ❌ Invalid

5. Case Insensitivity

Filter values are case insensitive.

Example: The queries below return the same results:

account_id.eq=abc123
account_id.eq=ABC123
account_id.eq=aBc123

6. Attribute Uniqueness

Each attribute should appear only once in a query. If repeated, only the last occurrence is considered.

Example:

account_id.eq=12345&&account_id.eq=67890&&account_id.not=54321

Only the last value, account_id.not=54321 is considered, other conditions are ignored.

7. Query Wrapping

Enclose the filter query in parentheses ().

Example: The query and the API path should be appended as:

/api/path/?filters=(account_id.eq=12345)

8. Query Parameter Precedence

If an attribute appears inside and outside the filters query, the one inside takes precedence.

Example:

/api/path/?account_id=12345&&filters=(account_id.eq=67890)

Results will only contain items filtered according to account_id.eq=67890, ignoring account_id=12345.

9. URI Encoding

URI encode the query befire sending it servers to ensure proper transmission.

Example:

Original query:

account_id.eq=12345&&format.eq=[json,xml]&&type.not=csv

Final API request:

/api/path/?filters=(account_id.eq=12345&&format.eq=[json,xml]&&type.not=csv)

Encoded version:

/api/path/?filters=%28account_id.eq%3D12345%26%26format.eq%3D%5Bjson%2Cxml%5D%26%26type.not%3Dcsv%29

Examples

Here are a few example formats for valid queries.

Query
attribute1.eq=[value1a,value1b,value1c]
attribute1.eq=[value1a,value1b,value1c]&&attribute2.eq=value2&&attribute3.eq=value3
attribute1.eq=[value1a,value1b,value1c]&&attribute2.eq=value2&&attribute3.eq=[value3a,value3b]
attribute1.not=value1
attribute1.not=[value1a,value1b,value1c]
attribute1.not=[value1a,value1b,value1c]&&attribute2.eq=value2&&attribute3.eq=value3
attribute1.not=[value1a,value1b,value1c]&&attribute2.not=value2&&attribute3.eq=[value3a,value3b]

Use case-based examples

Getting only "story" data from Instagram for a particular account
account_id.eq=<unique_account_id>&&type.eq=STORY
Getting everything except "story" data from Instagram for a particular account
account_id.eq=<unique_account_id>&&type.not=STORY
Getting all audio and video data except "story" from Instagram for a particular account
account_id.eq=<unique_account_id>&&format.eq=[AUDIO,VIDEO]&&type.not=STORY

Currently Supported APIs

`GET /v1/social/contents`

Attribute	Operator	Supports arrays	Examples
account_id	eq	Yes	`account_id.eq=value` `account_id.eq=[value1,value2,value3]`
format	eq	Yes	`format.eq=value` `format.eq=[value1,value2,value3]`
format	not	Yes	`format.not=value` `format.not=[value1,value2,value3]`
type	eq	Yes	`type.eq=value` `type.eq=[value1,value2,value3]`
type	not	Yes	`type.not=value` `type.not=[value1,value2,value3]`
work_platform_id	eq	Yes	`work_platform_id.eq=value` `work_platform_id.eq=[value1,value2,value3]`
work_platform_id	not	Yes	`work_platform_id.not=value` `work_platform_id.not=[value1,value2,value3]`
platform_username	eq	Yes	`platform_username.eq=value` `platform_username.eq=[value1,value2,value3]`
user_id	eq	Yes	`user_id.eq=value` `user_id.eq=[value1,value2,value3]`

`GET /v1/social/content-groups`

Attribute	Operator	Supports arrays	Examples
account_id	eq	Yes	`account_id.eq=value` `account_id.eq=[value1,value2,value3]`
format	eq	Yes	`format.eq=value` `format.eq=[value1,value2,value3]`
format	not	Yes	`format.not=value` `format.not=[value1,value2,value3]`
type	eq	Yes	`type.eq=value` `type.eq=[value1,value2,value3]`
type	not	Yes	`type.not=value` `type.not=[value1,value2,value3]`
work_platform_id	eq	Yes	`work_platform_id.eq=value` `work_platform_id.eq=[value1,value2,value3]`
work_platform_id	not	Yes	`work_platform_id.not=value` `work_platform_id.not=[value1,value2,value3]`
platform_username	eq	Yes	`platform_username.eq=value` `platform_username.eq=[value1,value2,value3]`
user_id	eq	Yes	`user_id.eq=value` `user_id.eq=[value1,value2,value3]`

`GET /v1/social/comments`

Attribute	Operator	Supports arrays	Examples
content_id	eq	Yes	`content_id.eq=value` `content_id.eq=[value1,value2,value3]`
content_id	not	Yes	`content_id.not=value` `content_id.not=[value1,value2,value3]`
commenter_id	eq	Yes	`commenter_id.eq=value` `commenter_id.eq=[value1,value2,value3]`
commenter_id	not	Yes	`commenter_id.not=value` `commenter_id.not=[value1,value2,value3]`
commenter_username	eq	Yes	`commenter_username.eq=value` `commenter_username.eq=[value1,value2,value3]`
commenter_username	not	Yes	`commenter_username.not=value` `commenter_username.not=[value1,value2,value3]`

If you need filtering capabilities on more APIs or additional attributes, feel free to reach out to us at [email protected]. Your feedback helps us improve!

Was this helpful?