documentation/retention.md at main

mirror of https://github.com/mastodon/documentation synced 2025-04-11 22:56:17 +02:00

feat: Document datetime and date formats (#1565 )

Add a new document that precisely describes the string representation of
datetime and date types.

The previous description of them as "ISO 8601 Datetime" was very
imprecise, as ISO 8601 describes many different ways of representing a
datetime and date.

Specify the datetime format precisely as the ISO 8601 profile described
in RFC 3339, and the date format precisely as the "Complete date" format
from the W3C note on date and time formats.

Adjust all the references to ISO 8601 datetimes or dates to link back
to the definition.

Fixes #1420

2024-11-27 15:08:51 +00:00

3.7 KiB

Raw Permalink Blame History

title

description

aliases

retention API methods

Show retention data over time.

docs

name	parent	identifier
retention	methods-admin	methods-admin-retention

/methods/admin/retention

/api/methods/admin/retention

Calculate retention data

POST /api/v1/admin/retention HTTP/1.1

Generate a retention data report for a given time period and bucket.

Returns: Array of [Admin::Cohort]({{< relref "entities/Admin_Cohort" >}})
OAuth: User token + admin:read
Permissions: View Dashboard
Version history:
3.5.0 - added
4.0.0 - support custom roles and permissions

Request

Headers

Authorization: {{}} Provide this header with Bearer <user_token> to gain authorized access to this API method.

Form data parameters

start_at: {{}} String (Datetime). The start date for the time period. If a time is provided, it will be ignored.
end_at: {{}} String (Datetime). The end date for the time period. If a time is provided, it will be ignored.
frequency: {{}} String (Enumerable oneOf). Specify whether to use day or month buckets. If any other value is provided, defaults to day.

Response

200: OK

Monthly retention data for the month of 2022-09, given that 2 users registered during 2022-09 and were active at least once during that month.

[
	{
		"period": "2022-09-01T00:00:00+00:00",
		"frequency": "month",
		"data": [
			{
					"date": "2022-09-01T00:00:00+00:00",
					"rate": 1.0,
					"value": "2"
			}
		]
	}
]

Daily retention data for the week between 2022-09-08 and 2022-09-14, given that 2 users registered on 2022-09-08 and 1 of those users stopped being active after 2022-09-09.

[
  {
    "period": "2022-09-08T00:00:00+00:00",
    "frequency": "day",
    "data": [
      {
        "date": "2022-09-08T00:00:00+00:00",
        "rate": 1,
        "value": "2"
      },
      {
        "date": "2022-09-09T00:00:00+00:00",
        "rate": 1,
        "value": "2"
      },
      {
        "date": "2022-09-10T00:00:00+00:00",
        "rate": 0.5,
        "value": "1"
      },
      // ...
      {
        "date": "2022-09-14T00:00:00+00:00",
        "rate": 0.5,
        "value": "1"
      }
    ]
  },
  {
    "period": "2022-09-09T00:00:00+00:00",
    "frequency": "day",
    "data": [
      {
        "date": "2022-09-09T00:00:00+00:00",
        "rate": 0,
        "value": "0"
      },
		// ...
      {
        "date": "2022-09-14T00:00:00+00:00",
        "rate": 0,
        "value": "0"
      }
    ]
  },
  {
    "period": "2022-09-10T00:00:00+00:00",
    "frequency": "day",
    "data": [
      {
        "date": "2022-09-10T00:00:00+00:00",
        "rate": 0,
        "value": "0"
      },
		// ...
      {
        "date": "2022-09-14T00:00:00+00:00",
        "rate": 0,
        "value": "0"
      }
    ]
  },
  // ...
  {
    "period": "2022-09-14T00:00:00+00:00",
    "frequency": "day",
    "data": [
      {
        "date": "2022-09-14T00:00:00+00:00",
        "rate": 0,
        "value": "0"
      }
    ]
  }
]

If any of the parameters are missing, cohort calculation will fail and an empty array will be returned.

[]

403: Forbidden

Authorized user is missing a permission, or invalid or missing Authorization header

{
  "error": "This action is not allowed"
}

3.7 KiB Raw Permalink Blame History