Skip to main content

Search

Let us guide you!

Get Filtered Data from a Table: filterRowIds

Updated on

The TimeTonic API allows you to retrieve rows from a table by filtering them directly in the request. To do this, you use the getTableValues function with the filterRowIds parameter (also called filtered rows).
Visit the API documentation page here.

Before you start

You must have an API key (Sesskey) and the numeric column identifiers (field_id), which can be retrieved via getTableValues. The user associated with the key must have access to the targeted table.

Method 1: Reuse an already filtered view

The simplest way is to point to an existing TimeTonic view whose filters are already configured. In filterRowIds, pass the view's ID as the value of applyViewFilters:

{ "applyViewFilters": 12345 }
  • When I open a record in TimeTonic, the URL contains the view ID

Method 2: Define your own filter (filterGroup)

If you don't want to rely on a view, pass a filterGroup object in applyViewFilters.

A filterGroup contains an operator (and or or) and a list of filters. Each filter targets a column (field_id) with a predicate and a value (operand).

Example: retrieve rows where column 1735324 (of type date) is after May 1, 2020.

{
  "applyViewFilters": {
    "filterGroup": {
      "operator": "and",
      "filters": [
        {
          "id": "tmpId",
          "field_id": "1735324",
          "filter_type": "date",
          "json": { "predicate": "after", "operand": "2020-05-01" }
        }
      ]
    }
  }
}
Syntax elements

The tags filterGroup, filters, and json are mandatory. The id key is an arbitrary and unique filter identifier: for a temporary filter, use the value tmpId. The filter_type corresponds to the type of the targeted column (see the reference table below).
In case of syntax error. Incorrect syntax returns a valid but empty response: no rows are returned and the response shows rowInfosLength: 0. Check tag names and column IDs before concluding that the table contains no data.

Method 3: Combine AND and OR (nested groups)

A filter can itself be a filterGroup: give it filter_type: "filterGroup" and its own operator. This allows you to combine AND and OR conditions at multiple levels.

Example: retrieve rows where (column 5555 equals 3654) AND (column 12345 equals 789 OR 543) AND (column 3214 is on or after a date).

{
  "applyViewFilters": {
    "filterGroup": {
      "operator": "and",
      "filters": [
        {
          "id": "tmpId",
          "field_id": 5555,
          "filter_type": "int",
          "json": { "predicate": "equals", "operand": 3654 }
        },
        {
          "filter_type": "filterGroup",
          "operator": "or",
          "filters": [
            { "id": "tmpId", "field_id": 12345, "json": { "predicate": "is", "operand": "789" } },
            { "id": "tmpId", "field_id": 12345, "json": { "predicate": "is", "operand": "543" } }
          ]
        },
        {
          "id": "tmpId",
          "field_id": 3214,
          "filter_type": "date",
          "json": { "predicate": "on or after", "operand": "2026-01-01" }
        }
      ]
    }
  }
}

The root group applies the and operator to its three elements. The second element is itself a group with the or operator: its two conditions are alternatives. This nesting can be repeated to build more refined logic.

Filtering by field content described here concerns direct API calls. The native TimeTonic node of some automation tools can filter only by row ID (RowID): in that case, build the getTableValues request yourself to filter by column value.

Reference: operators and predicates

An operator links the filters of a group. A predicate defines the condition applied to a column, according to its type.

Operator Effect
and All conditions in the group must be true (AND).
or At least one condition in the group must be true (OR).

Column type and filter_type

The filter_type to specify depends on the type of the targeted TimeTonic column:

TimeTonic Column filter_type
Checkbox boolean
Integer number int
Decimal number float
URL text
External form text
Short text text
Medium text text
Long text text
Email text
Attachments files
Date date or datetime
Comments comments
Link to another table link
Column from a linked table link
Selection (list from another table) enum
Conditional selection (list from another table) enum
Conditional text (list from another table) text
Color selection text
Text color text
Mask text
Formula text
Auto number int
Last modification datetime
Phone number text
Auto document text
Encrypted column text
Book members text

Predicates by family

The applicable predicate depends on the filter_type of the targeted column. Click a predicate to copy it, then paste it into the predicate key of your filter.

Generic text, enum, link, files, comments, boolean
is is not is empty is not empty contains does not contains
Numeric int, float
equals not equals less than greater than less or equal than greater or equal than min max top bottom is empty is not empty
Date and datetime date, datetime
on not on before after before today after today on or before on or before today on or after on or after today in quarter in month in this week current month current year not current month not current year is empty is not empty
Specific to datetime
in the last 5 min in the last 15 min in the last hour
Link link, enum
is any of is not any of is me is book code
Text text
is book code begins with
Click a predicate to copy it to the clipboard.
For large tables, getTableValues supports pagination via offset (page number) and maxRows (number of rows per page). The format: rows parameter returns values by row rather than by column.

Learn more

Get values from a table

Retrieve columns and rows from a table with getTableValues.

Read more →

Learn more

Example of creation, update, and search

Ready-to-use Postman collection for getTableValues and createOrUpdateTableRow.

Read more →

Learn more

API overview

API key, access, and basic principles of the TimeTonic API.

Read more →