Skip to main content

Get Data As Records Through Get

GET 
/records

Retrieves and aggregates all data for completed flows that match the given query parameters, returning the results as a list of flattened records.

This endpoint takes nested raw Items (which may come from multiple sessions or flows) and converts them into a single-level dictionary per record. The flattening process transforms nested keys into dot-separated paths, where the flow step ID of each module is used as the second component in the key. When arrays are encountered (for example, when a module returns multiple photos), each element is assigned an index (e.g., ".1", ".2", etc.) to distinguish between values.

When the join_by parameter is specified (e.g., join_by=barcode_scanning.barcode.code), data from different sessions that share the same value for that field are aggregated into a single record. During aggregation, for every key (or "path"), the last non-null value encountered (based on global ordering) is retained. This ensures that different data gathered in separate flows for the same datapoint are combined into one coherent flat record.

Nested JSON Structure Example:

Consider a raw Item with nested data:

{
    "created_at": "2025-03-05T14:38:22.903000",
    "updated_at": "2025-03-05T14:38:22.903000",
    "_id": "67c861de20bb29fb40d2cbbd",
    "started_at": "2025-03-05T14:38:10",
    "ended_at": "2025-03-05T14:38:20",
    "flow_id": "APIDocsFlow1",
    "photographing": [
        {
            "flow_step_id": "picz",
            "started_at": "2025-03-05T14:38:15",
            "ended_at": "2025-03-05T14:38:20",
            "photos": [
                {
                    "date": "2025-03-05T14:38:20",
                    "url": "https://dimmy.s3.amazonaws.com/66826269369bbc3d56b479ce/67c861dc45b0e6fb32ff2ca1"
                }
            ]
        }
    ],
    "barcode_scanning": [
        {
            "flow_step_id": "barcode",
            "started_at": "2025-03-05T14:38:10",
            "ended_at": "2025-03-05T14:38:15",
            "code": "A0155C35"
        }
    ]
}

In this structure:

The module for barcode scanning uses its flow_step_id ("barcode") to generate keys like:

  • barcode_scanning.barcode.started_at
  • barcode_scanning.barcode.ended_at
  • barcode_scanning.barcode.code

The photographing module (with flow_step_id "picz") returns an array for photos. The photos are flattened as:

  • photographing.picz.photos.1.date
  • photographing.picz.photos.1.url (Additional elements would get suffixes .2, .3, etc.)

Flattened Record Example (with Aggregation via join_by):

Request:

GET /records?join_by=barcode_scanning.barcode.code&limit=1

Response:

[
    {
        "created_at": "2025-03-05T14:38:22.903000",
        "updated_at": "2025-03-05T14:38:22.903000",
        "_id": "67c861de20bb29fb40d2cbbd",
        "started_at": "2025-03-05T14:38:10",
        "ended_at": "2025-03-05T14:38:20",
        "flow_id": "APIDocsFlow1",
        "photographing.picz.started_at": "2025-03-05T14:38:15",
        "photographing.picz.ended_at": "2025-03-05T14:38:20",
        "photographing.picz.photos.1.date": "2025-03-05T14:38:20",
        "photographing.picz.photos.1.url": "https://dimmy.s3.amazonaws.com/66826269369bbc3d56b479ce/67c861dc45b0e6fb32ff2ca1",
        "barcode_scanning.barcode.started_at": "2025-03-05T14:38:10",
        "barcode_scanning.barcode.ended_at": "2025-03-05T14:38:15",
        "barcode_scanning.barcode.code": "A0155C35",
        "scanner_account": "optioryx_admin"
    }
]

In this example, data from four different sessions was aggregated into one record based on the shared value of barcode_scanning.barcode.code. For each dot-notated path, the last non-null value is kept, so that data from multiple flows for the same datapoint is combined into a single, coherent flat record.

Request​

Query Parameters

    join_by Join By

    Field in dot notation to join by. If multiple items exist with the same value for this field, and at least one of those items appear in the query results, they will be merged into one record. For every property, the last known non-null value will be used.

    queries string[]

    List of queries to filter by. Does fuzzy matching of the queries in all string fields, with an OR operator between queries.

    exact_queries string[]

    List of queries to filter by. Checks for every query if the value appears exactly at least once in any string field, with an OR operator between queries.

    skip Skip

    Number of records to skip (pagination)

    limit Limit

    Maximum number of records to return (pagination)

    start_date date-time

    Include only records created after this date (formatted as string, example: 2024-12-06T08:36:30.192143)

    end_date date-time

    Include only records created before this date (formatted as string, example: 2024-12-06T08:36:30.192143)

    scanner_accounts string[]

    List of account name queries. All items scanned by accounts that match any of these queries will be returned. If empty, data collected by any subaccount will be included.

    scanner_account_ids string[]

    List of account name queries. All items scanned by accounts that match any of these queries will be returned. If empty, data collected by any subaccount will be included. This parameter takes precedence over scanner_accounts.

    flow_ids string[]

    List of flow IDs to filter by

    sort_by Sort By

    Path to sort by, in dot notation

    sort_direction Sort Direction

    Direction to sort, 1 for ascending, -1 for descending

    hidden_paths string[]

    List of fields to hide, in path notation

    included_paths string[]

    List of fields to include, in path notation. If empty, all fields are included. Takes precedence over hidden_paths.

    not_null_paths string[]

    List of fields that must not be null, in path notation

    path_queries string[]

    Queries in the format path:value!. Path signifies the path to the field to query, value is the value to match, and ! signifies an exact match, if ! is not present, it will be a fuzzy match.

Responses​

Successful Response

Schema
  • Array [

    • object

  • ]
Loading...