ChartMogul Filter Language

The ChartMogul Filter Language (CFL) is a string-based syntax for filtering data.

CFL allows you to programmatically apply the same filters that you use in the ChartMogul interface. When you apply filters in the app, the resulting CFL string appears in your browser’s address bar.

Metrics API endpoints accept an optional filters parameter that uses CFL to define filter criteria.

Syntax

CFL has the following format:

[filter]~[operator]~[value]~AND~[filter]~[operator]~[value]~AND~…

Key rules

• Separators: Use ~ (tilde) characters to separate filters, operators and values.
• Operators: Join multiple filters with ~AND~. CFL only supports the AND operator (all conditions must match).
• String format: Enclose string values in single quotes, e.g., 'US', 'Enterprise'.
• Multiple values: Separate multiple values with commas, e.g., 'US','FR','DE'.

Special case: plan filters

Plan and plan group filters have a unique behavior: when connected with the AND operator, they function as an OR condition. This behavior reflects how the filters work in the app.

Let’s take the following expression as an example:

plan~ANY~<PLAN_UUID>~AND~plan_group~ANY~<PLAN_GROUP_UUID>

Even though the filters are connected with the AND operator, a plan must match either the plan UUID OR the plan group UUID.

Operators

CFL uses the following operators:

Set operators

• ALL — Matches only if the record contains all of the specified values.
• ANY — Matches if the record contains any of the specified values.
• NONE — Matches if the record contains none of the specified values.

Comparison operators

• EQ — Equal to; matches if the value equals the specified value.
• NOT_EQ — Not equal to; matches if the value does not equal the specified value.
• GT — Greater than; matches if the value is greater than the specified value.
• GTE — Greater than or equal to; matches if the value is greater than or equal to the specified value.
• LT — Less than; matches if the value is less than the specified value.
• LTE — Less than or equal to; matches if the value is less than or equal to the specified value.
• IS_NULL_OR_EQ — Matches if the value is NULL or equals the specified value.

Range operators

• BETWEEN — Specifies a range with two comma-separated values.

Containment operators

• CONTAINS — Matches if the string contains the specified value.
• NOT_CONTAINS — Matches if the string does not contain the specified value.

Identity operators

• IS — Checks if the value matches the specified value.
• IS_NOT — Checks if the value does not match the specified value.

Review operators available for each filter.

Getting CFL from the app

The easiest way to construct a valid CFL string is to obtain it from the app:

1. Navigate to Reports in ChartMogul.
2. Apply your desired filters.
3. Copy the filters parameter value from the browser address bar.

Using CFL in API requests

Use CFL as the value of the optional filters parameter when calling Metrics API endpoints. The parameter is only available for cURL calls.

Either use URL-encoded CFL copied from the address bar:

curl -X GET "https://api.chartmogul.com/v1/metrics/arr" \
  -u YOUR_API_KEY: \
  -d start-date=2025-01-01 \
  -d end-date=2025-03-31 \
  -d interval=month \
  -d filters=region~ANY~%27US%27%2C%27FR%27%2C%27DE%27~AND~mrr~GT~150

Or write CFL manually (requires double quotes around the key-value pair):

curl -X GET "https://api.chartmogul.com/v1/metrics/arr" \
  -u YOUR_API_KEY: \
  -d start-date=2025-01-01 \
  -d end-date=2025-03-31 \
  -d interval=month \
  -d "filters=region~ANY~'US','FR','DE'~AND~mrr~GT~150"

Available filters

The following table lists filters that can be used in CFL expressions, along with supported operators and example values. Click a filter to open a page with its detailed description.