Skip to main content Link Menu Expand (external link) Document Search Copy Copied
Zuko Knowledge Base

Optional parameters

Table of contents
  1. Filters
  2. Session outcome
  3. Including session-related information
    1. Field-level metrics
    2. Field-level metrics over time (flurries)
    3. Events
    4. Event metrics
  4. Next page ID

The following are optional parameters which can be provided on every request.

Note: All parameters should be provided as search parameters in the URL.

Filters

If you provide filters on the request, the API will filter sessions in Zuko based on those which you provide. These filters map to attributes.

Filters are defined as a hash.

Example:

filters[deviceType]=mobile

This would return only sessions from mobile devices.

Multiple filters can be defined on a request. Filters are combined with AND logic.

Example:

filters[deviceType]=mobile
filters[browserFamily]=Chrome

This would return sessions from Chrome running on mobile devices.

Session outcome

The Sessions API supports filtering sessions on the outcome of the session. The following are the session outcomes which the API supports filtering on:

  • viewed
  • started
  • completed

Each outcome is defined as a separate parameter on the request and must contain a boolean value.

Example:

viewed=true

The above would return only sessions where the form was viewed by the visitor.

These outcomes can be combined to form a more complex query.

Example:

viewed=true
started=true
completed=false

The above would return only sessions where your form has been viewed by the visitor; they have started to interact with your form, but the form was not successfully completed. We refer to this type of session as an abandonment.

Note: A valid combination of session outcome filters must be provided.

An example of an invalid combination would be:

viewed=false
started=true

This is classed as an invalid combination, as a visitor must have viewed the form, in order to have started the form.

Whilst the primary unit of data which the Sessions API returns are sessions, it also supports including related units of data in the response.

These are:

  • fields: Metrics for the fields which were interacted with during the session
  • flurries: Metrics for the fields which were interacted with during the session, but split out over time as the visitor moves through the form.
  • events: Every custom event which occurs during the session.
  • event_metrics: Aggregated data on custom events which occur during the session.

This extra data can be included in the response by defining them in the include parameter.

Example:

include[]=fields
include[]=flurries
include[]=events
include[]=event_metrics

Field-level metrics

Field-level metrics are aggregated from all of the interactions with each field.

Example:

include[]=fields

See the fields response schema section for more information on the metrics returned.

Field-level metrics over time (flurries)

Field-level metrics can also be provided over the duration of the session. The time-based dimension which we support for this is a flurry.

Example:

include[]=flurries

See the flurries response schema section for more information on the metrics returned.

Events

Custom events which occur within the session can be included in the response.

Example:

include[]=events

See the events response schema section for more information on the metrics returned.

Event metrics

Aggregated metrics on the events which occur within the session can be included in the response.

Example:

include[]=event_metrics

See the event metrics response schema section for more information on the metrics returned.

Next page ID

Allows the next page of sessions to be retrieved from the API.

See pagination for more information on when to use this.

Example:

next_page_id=NUX2Nkb4NCB2MkTwMB==