Session Query API

The POST /api/sessions/query endpoint enables complex filtering on both Session entity properties and the MetadataJson column using LINQ expressions, with support for ordering by both Session entity properties and MetadataJson paths.

Endpoint


POST /api/sessions/query

Request Body


{
  "filter": FilterNode,
  "limit": number,
  "offset": number,
  "orderBy": OrderByDescriptor[]
}

Parameters

Parameter	Type	Required	Description
`filter`	FilterNode	No	Complex filter conditions for Session properties or MetadataJson
`limit`	number	No	Maximum number of results to return
`offset`	number	No	Number of results to skip for pagination
`orderBy`	OrderByDescriptor[]	No	List of ordering criteria

Filter Node Structure

A FilterNode can be either a leaf condition or a logical operator combining multiple conditions.

Leaf Condition


{
  "path": "string",
  "op": "string",
  "value": any
}

Field	Type	Description
`path`	string	Session property name or dot-notation path to a JSON field (e.g., `_bio_signals.heartrate_valid_pct`)
`op`	string	Comparison operator
`value`	any	Value to compare against

Logical Operators


{
  "and": FilterNode[]
}


{
  "or": FilterNode[]
}

Supported Session Properties for Filtering

The following Session entity properties can be filtered directly:

Property	Type	Supported Operators
`id`	Guid	`eq`, `ne`
`name`	string	`eq`, `ne`, `contains`, `startsWith`, `endsWith`
`email`	string	`eq`, `ne`, `contains`, `startsWith`, `endsWith`
`projectId`	int	`eq`, `ne`, `gt`, `gte`, `lt`, `lte`
`sessionTemplateId`	int	`eq`, `ne`, `gt`, `gte`, `lt`, `lte`
`simulationName`	string	`eq`, `ne`, `contains`, `startsWith`, `endsWith`
`logoUrl`	string (nullable)	`eq`, `ne`, `contains`, `startsWith`, `endsWith`
`userId`	Guid (nullable)	`eq`, `ne`
`createdAt`	DateTime (nullable)	`eq`, `ne`, `gt`, `gte`, `lt`, `lte`

Any path that is not a Session property will be treated as a MetadataJson path.

Supported Operators

Operator	Description	Example
`eq`	Equal to	`{ "path": "name", "op": "eq", "value": "Training Session" }`
`ne`	Not equal to	`{ "path": "scenario_type", "op": "ne", "value": "Training" }`
`gt`	Greater than	`{ "path": "projectId", "op": "gt", "value": 2 }`
`gte`	Greater than or equal	`{ "path": "_bio_signals.rows", "op": "gte", "value": 300 }`
`lt`	Less than	`{ "path": "data_quality.samples.total", "op": "lt", "value": 500 }`
`lte`	Less than or equal	`{ "path": "_bio_signals.heartrate_valid_pct", "op": "lte", "value": 90.0 }`
`contains`	Contains value (string/array)	`{ "path": "name", "op": "contains", "value": "Demo" }`
`startsWith`	String starts with	`{ "path": "simulationName", "op": "startsWith", "value": "Driving" }`
`endsWith`	String ends with	`{ "path": "email", "op": "endsWith", "value": "@example.com" }`

OrderBy Descriptor


{
  "path": "string",
  "direction": "asc" | "desc"
}

Field	Type	Description
`path`	string	Property name (Session field) or dot-notation path (MetadataJson field)
`direction`	string	Sort direction: `asc` (default) or `desc`

Supported Session Properties for Ordering

id
name
email
createdAt
simulationName
projectId
sessionTemplateId
logoUrl
userId

Any other path will be treated as a MetadataJson path.

Example MetadataJson Structure


{
  "ScenarioInstanceId": "8624695e-097e-4514-8cbf-13530b45be0a",
  "machineGroup": 1,
  "started_date": "2024-01-15T09:30:00Z",
  "user_list": [
    "a1b2c3d4-1111-1111-1111-111111111111",
    "b2c3d4e5-2222-2222-2222-222222222222"
  ],
  "_bio_signals": {
    "heartrate_valid_pct": 100.0,
    "pupil_valid_pct": 0.0,
    "rows": 304
  },
  "data_quality": {
    "files": { "csv": 2, "total": 3 },
    "samples": { "total": 304, "gaze_finite_pct": 91.118 }
  },
  "scenario_name": "Driving Demo",
  "scenario_type": "Generic Scenario",
  "user_count": 2
}

Example Queries

1. Filter by Session Property (Name)

Filter sessions where name contains “Training”:


curl -X POST http://localhost:5000/api/sessions/query \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { "path": "name", "op": "contains", "value": "Training" },
    "limit": 10
  }'

2. Filter by Session Property (Project ID)

Filter sessions for a specific project:


curl -X POST http://localhost:5000/api/sessions/query \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { "path": "projectId", "op": "eq", "value": 1 },
    "limit": 50
  }'

3. Filter by Session Property (Created Date Range)

Filter sessions created after a specific date:


curl -X POST http://localhost:5000/api/sessions/query \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { "path": "createdAt", "op": "gte", "value": "2024-01-01T00:00:00Z" }
  }'

4. Filter by MetadataJson (Scenario Name)

Filter sessions where scenario_name equals “Driving Demo”:


curl -X POST http://localhost:5000/api/sessions/query \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { "path": "scenario_name", "op": "eq", "value": "Driving Demo" },
    "limit": 10
  }'

5. Filter by MetadataJson (Numeric Comparison)

Filter sessions where heartrate validation is above 90%:


curl -X POST http://localhost:5000/api/sessions/query \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { "path": "_bio_signals.heartrate_valid_pct", "op": "gt", "value": 90.0 }
  }'

6. Filter by MetadataJson (Machine Group)


curl -X POST http://localhost:5000/api/sessions/query \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { "path": "machineGroup", "op": "eq", "value": 1 },
    "limit": 50
  }'

7. Contains Filter (User in List)

Find sessions containing a specific user in MetadataJson:


curl -X POST http://localhost:5000/api/sessions/query \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { 
      "path": "user_list", 
      "op": "contains", 
      "value": "a1b2c3d4-1111-1111-1111-111111111111" 
    }
  }'

8. AND Condition (Combined Session Property and MetadataJson)

Filter sessions for projectId 1 AND with heartrate > 85%:


curl -X POST http://localhost:5000/api/sessions/query \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "and": [
        { "path": "projectId", "op": "eq", "value": 1 },
        { "path": "_bio_signals.heartrate_valid_pct", "op": "gt", "value": 85.0 }
      ]
    }
  }'

9. OR Condition

Filter sessions that are either “Generic Scenario” OR have high pupil validation:


curl -X POST http://localhost:5000/api/sessions/query \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "or": [
        { "path": "scenario_type", "op": "eq", "value": "Generic Scenario" },
        { "path": "_bio_signals.pupil_valid_pct", "op": "gt", "value": 70.0 }
      ]
    }
  }'

10. Complex Nested Filter (Session Properties and MetadataJson)

Filter sessions in projectId 2 AND (name contains “Demo” OR heartrate > 90%):


curl -X POST http://localhost:5000/api/sessions/query \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "and": [
        { "path": "projectId", "op": "eq", "value": 2 },
        {
          "or": [
            { "path": "name", "op": "contains", "value": "Demo" },
            { "path": "_bio_signals.heartrate_valid_pct", "op": "gt", "value": 90.0 }
          ]
        }
      ]
    },
    "limit": 100
  }'

11. With Ordering by Session Property

Order by creation date descending:


curl -X POST http://localhost:5000/api/sessions/query \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { "path": "scenario_type", "op": "eq", "value": "Generic Scenario" },
    "orderBy": [{ "path": "createdAt", "direction": "desc" }],
    "limit": 50
  }'

12. With Ordering by MetadataJson Path

Order by heartrate validation percentage descending:


curl -X POST http://localhost:5000/api/sessions/query \
  -H "Content-Type: application/json" \
  -d '{
    "orderBy": [{ "path": "_bio_signals.heartrate_valid_pct", "direction": "desc" }],
    "limit": 20
  }'

13. Pagination

Get the second page of results (skip first 50, take next 50):


curl -X POST http://localhost:5000/api/sessions/query \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { "path": "projectId", "op": "eq", "value": 1 },
    "limit": 50,
    "offset": 50,
    "orderBy": [{ "path": "createdAt", "direction": "desc" }]
  }'

14. Date Range Filter on MetadataJson

Filter sessions started after a specific date:


curl -X POST http://localhost:5000/api/sessions/query \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { "path": "started_date", "op": "gt", "value": "2024-01-16T00:00:00Z" }
  }'

15. Multiple OrderBy Criteria

Order by name ascending, then by createdAt descending:


curl -X POST http://localhost:5000/api/sessions/query \
  -H "Content-Type: application/json" \
  -d '{
    "orderBy": [
      { "path": "name", "direction": "asc" },
      { "path": "createdAt", "direction": "desc" }
    ],
    "limit": 100
  }'

Response

Returns a response object containing an array of Session objects matching the filter criteria.


{
  "status": true,
  "template": {
    "sessions": [
      {
        "id": "guid",
        "name": "Session Name",
        "email": "user@example.com",
        "projectId": 1,
        "sessionTemplateId": 1,
        "simulationName": "Simulation",
        "logoUrl": "https://...",
        "userId": "guid",
        "createdAt": "2024-01-15T09:30:00Z",
        "metadataJson": { ... }
      }
    ],
    "totalCount": 42,
    "limit": 100,
    "offset": 0
  }
}