> For the complete documentation index, see [llms.txt](https://everyday-digital.gitbook.io/falkor-dev-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://everyday-digital.gitbook.io/falkor-dev-docs/analytics/audience/frequency.md).

# Frequency

The Frequency endpoint allows viewing analytics of total sessions vs unique sessions with a given interval (hour, day, month, year). This end point allows frequency analytics to be viewed for Apps, Stories, Pathways OR Streams.  

## Available Frequency Endpoints

`v1/analytics/frequency/apps`\
Get frequency analytics for an app or a list of apps.

`v1/analytics/frequency/pathways`\
Get frequency analytics for a pathways or a list of pathways.

`v1/analytics/frequency/streams`\
Get frequency analytics for a stream or a list of streams.

`v1/analytics/frequency/stories`\
Get frequency analytics for a story or a list of stories.

## Parameters <a href="#parameters" id="parameters"></a>

The items parameter allows you to filter items based on the name or ID of the item. If the item parameter is not provided the endpoint will return the latest 10 items.

<table><thead><tr><th width="194"></th><th></th></tr></thead><tbody><tr><td><strong>Key</strong></td><td><strong>Value</strong></td></tr><tr><td><strong>items</strong></td><td><strong>Array of Strings</strong> <br>Item name or ID</td></tr><tr><td><strong>Interval</strong></td><td><strong>String</strong> <br>day, hour, month, year defaults to month.</td></tr><tr><td><strong>steps</strong></td><td><strong>Int</strong><br>Number of steps to use between 1 - 24</td></tr></tbody></table>

## Examples

### Get App's Frequency For 7 Days

The example below retrieves a single app with an `interval` set to "day" and the `steps` "7". This will give a frequency result for 7 days.&#x20;

```
curl -X POST \
  v1/analytics/frequency/apps \
  -H 'Authorization: Basic <Your Base64 Encoded Token>'\
  -d '{
    "items" : ["Learning App"],
    "interval" : "day",
    "steps" : 7
  }'
```

### Get Frequency For 12 Months

The example below retrieves the latest 10 stories with an `interval` set to "month" and the `steps` set to "12". This will give a frequency of 12 months for each item.&#x20;

```
curl -X POST \
  v1/analytics/frequency/stories \
  -H 'Authorization: Basic <Your Base64 Encoded Token>'\
  -d '{
    "interval" : "month",
    "steps" : 12
  }'
```

## Success Response

Whichever `frequency` endpoint you are using a successful response will return an array of items with each item containing a context item (app, pathway, stream or story) and corresponding `frequency` data. The example below shows a successful response when using the `frequency/apps` endpoint.

```
{
    "status": "success",
    "data": [
        {
            "app": {
                "name": "Falkor",
                "version": "2.10.1",
                "type": "app",
                "ID": "io.falkor.demo"
            },
            "frequency": [
                {
                    "interval": "month",
                    "range": [
                        "2021-12-01T00:00:00+02:00",
                        "2021-12-31T23:59:59+02:00"
                    ],
                    "sessions": 12,
                    "unique": 1
                },
                {
                    "interval": "month",
                    "range": [
                        "2022-01-01T00:00:00+02:00",
                        "2022-01-31T23:59:59+02:00"
                    ],
                    "sessions": 17,
                    "unique": 13
                },
                ..etc
            ]
        },
        ...etc
    ],
    "hash": "7ed75a2f94c199e29c5d55faa9e81858",
    "response_time": 0.18564820289611816
}
```