> 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/retention.md).

# Retention

The Retention endpoint allows viewing analytics on retention of users by cohorts. This end point allows retention analytics to be viewed for Apps, Stories, Pathways OR Streams. 

## Available Frequency Endpoints

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

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

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

`v1/analytics/retention/stories`\
Get retention 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></tbody></table>

## Examples

### Get Retention For Apps

The example below retrieves retention for a list of apps.

```
curl -X POST \
  v1/analytics/retention/apps \
  -H 'Authorization: Basic <Your Base64 Encoded Token>'\
```

### Get Retention For A Specific App

The example below retrieves retention for a single app.

```
curl -X POST \
  v1/analytics/retention/apps \
  -H 'Authorization: Basic <Your Base64 Encoded Token>'\
  -d '{
    "items" : ["Falkor"]
  }'
```

## Success Response

Whichever `retention` 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 `retention` data. The example below shows a successful response when using the `retention/apps` endpoint.

### Retention Item

|            |                                                                                     |
| ---------- | ----------------------------------------------------------------------------------- |
| **Key**    | **Type**                                                                            |
| **cohort** | <p><strong>String</strong><br>The name of the cohort for a given start and end.</p> |
| **start**  | <p><strong>String</strong><br>The start time of the cohort</p>                      |
| **end**    | <p><strong>String</strong><br>The end time of the cohort</p>                        |
| **weeks**  | <p><strong>Array Int</strong><br>Total of the returning users week by week.</p>     |

```
{
    "status": "success",
    "data": [
        {
            "app": {
                "name": "Falkor",
                "version": "2.10.1",
                "type": "app",
                "ID": "io.falkor.demo"
            },
            "cohorts": [
                {
                    "cohort": "All Users",
                    "start": "2021-12-31T00:00:00+02:00",
                    "end": "2022-02-25T00:00:00+02:00",
                    "weeks": [
                        100,
                        91,
                        98,
                        95,
                        95,
                        95,
                        93,
                        90
                    ]
                },
                {
                    "cohort": "31 Dec - 07 Jan",
                    "start": "2021-12-31T00:00:00+02:00",
                    "end": "2022-02-25T00:00:00+02:00",
                    "weeks": [
                        100,
                        95,
                        91,
                        96,
                        99,
                        91,
                        94,
                        96
                    ]
                },
                {
                    "cohort": "07 Jan - 14 Jan",
                    "start": "2022-01-07T00:00:00+02:00",
                    "end": "2022-02-25T00:00:00+02:00",
                    "weeks": [
                        100,
                        98,
                        93,
                        92,
                        94,
                        93,
                        92
                    ]
                },
                {
                    "cohort": "14 Jan - 21 Jan",
                    "start": "2022-01-14T00:00:00+02:00",
                    "end": "2022-02-25T00:00:00+02:00",
                    "weeks": [
                        100,
                        98,
                        92,
                        90,
                        95,
                        97
                    ]
                },
                {
                    "cohort": "21 Jan - 28 Jan",
                    "start": "2022-01-21T00:00:00+02:00",
                    "end": "2022-02-25T00:00:00+02:00",
                    "weeks": [
                        100,
                        100,
                        93,
                        96,
                        90
                    ]
                },
                {
                    "cohort": "28 Jan - 04 Feb",
                    "start": "2022-01-28T00:00:00+02:00",
                    "end": "2022-02-25T00:00:00+02:00",
                    "weeks": [
                        100,
                        97,
                        99,
                        93
                    ]
                },
                {
                    "cohort": "04 Feb - 11 Feb",
                    "start": "2022-02-04T00:00:00+02:00",
                    "end": "2022-02-25T00:00:00+02:00",
                    "weeks": [
                        100,
                        95,
                        94
                    ]
                },
                {
                    "cohort": "11 Feb - 18 Feb",
                    "start": "2022-02-11T00:00:00+02:00",
                    "end": "2022-02-25T00:00:00+02:00",
                    "weeks": [
                        100,
                        95
                    ]
                },
                {
                    "cohort": "18 Feb - 25 Feb",
                    "start": "2022-02-18T00:00:00+02:00",
                    "end": "2022-02-25T00:00:00+02:00",
                    "weeks": [
                        100
                    ]
                }
            ]
        },
        ...etc
    ],
    "hash": "d05e9fa21aba7c5a6d440b805f221a91",
    "response_time": 0.19922590255737305
}
```