> 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
}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://everyday-digital.gitbook.io/falkor-dev-docs/analytics/audience/retention.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.