Accessing Analytics via API

Flow XO allows you to retrieve the same analytics data found on the analytics tab via API

Authorization

You must authorize all calls to the Flow XO API using your API key and an authorization header. Details can be found here: https://support.flowxo.com/article/289-api-authorization

API Url

To use the Flow XO API, you will need to send HTTP requests to the following endpoint. The last part of the URL will depend on the method you are calling, but the base address is:

https://flowxo.com/api/insights

Listing Stats & Metrics

You can list the overall stats and time series metrics shown in the dashboard tab of Flow XO by issuing a GET request:

GET https://flowxo.com/api/insights?offset={utc_offset_in_minutes}&start={iso_8601_start_datetime}&end={iso_8601_end_datetime}&unit={hour|day|month}

For example:

GET https://flowxo.com/api/insights?offset=0&start=2021-10-01&end=2021-11-30&unit=month

The result will look like this:

{
    "stats": [
        {
            "_id": null,
            "active_users": 23,
            "total_users": 55,
            "new_users": 10,
            "triggers": 104,
            "received_messages": 106,
            "sent_messages": 146
        }
    ],
    "metrics": [
        {
            "_id": "2021-10",
            "_timestamp": "2021-10-01T00:00:00.000Z",
            "active_users": 22,
            "total_users": 54,
            "new_users": 9,
            "triggers": 100,
            "received_messages": 99,
            "sent_messages": 141
        },
        {
            "_id": "2021-11",
            "_timestamp": "2021-11-01T00:00:00.000Z",
            "active_users": 23,
            "total_users": 55,
            "new_users": 1,
            "triggers": 4,
            "received_messages": 7,
            "sent_messages": 5
        }
    ]
}

Stats

The 'stats' property provides a set of overall statistics for the date range in question, and corresponds to this element in the dashboard:

Metrics

The 'metrics' property returns a list of time series data points, one for each time unit in the date range. Each graph on the dashboard is given a single data point in the object for each time unit. In the example above the time unit was months, and the date range was 2021-10 to 2021-11, and so two data points are returned, one for October and one for November.

Please note the following possible parameters for this query, all of which are optional:

offset - the offset is the UTC offset in minutes. For example, if the timezone you are in is UTC-8, your offset will be -8 * 60, or -480. An offset of 0 (the default) will render times in UTC.
start - the start time, in an ISO 8601 format, of the date range you want returned. This can include a time component, but it is not required.
end - the end time, in an ISO 8601 format, of the date range. You can omit this for 'now'
unit - the granularity of the results. You can choose between month, day, and hour.

Top Messages

You can list the top messages on an account by issuing a GET request:

GET https://flowxo.com/api/insights/top_messages?start={iso_8601_start_datetime}&end={iso_8601_end_datetime}&limit={max_results}

And the result will look like:

[
    {
        "_id": "text me",
        "count": 18
    },
    {
        "_id": "hi",
        "count": 4
    },
    {
        "_id": "text ne",
        "count": 2
    },
    {
        "_id": "/start",
        "count": 1
    },
    {
        "_id": "convert a timestamp",
        "count": 1
    }
]

Please note the following possible parameters for this query, all of which are optional:

start - the start time, in an ISO 8601 format, of the date range you want returned. This can include a time component, but it is not required.
end - the end time, in an ISO 8601 format, of the date range. You can omit this for 'now'
limit - the number of results to return

Top Flows

You can list the top messages on an account by issuing a GET request:

GET https://flowxo.com/api/insights/top_flows?start={iso_8601_start_datetime}&end={iso_8601_end_datetime}&limit={max_results}

And the result will look like:

[
    {
        "_id": {
            "id": "616f1b6a1680ec001b9a4579",
            "name": "Untitled Broadcast"
        },
        "count": 93
    },
    {
        "_id": {
            "id": "5e4078ccbf034a59fd0b611d",
            "name": "Text Me"
        },
        "count": 19
    },
    {
        "_id": {
            "id": "615119f48188d75b1dd62763",
            "name": "Untitled Flow"
        },
        "count": 14
    },
    {
        "_id": {
            "id": "6104229e5fd0b00021b5e807",
            "name": "Deep Linking with Multiple Argument Parsing (b64 url)"
        },
        "count": 1
    },
    {
        "_id": {
            "id": "5e2e18a38575b0006eb996c5",
            "name": "Parse a Unix Timestamp"
        },
        "count": 1
    }
]

<br>

Please note the following possible parameters for this query, all of which are optional:

That's it! Let us know if you have any questions, feedback, or need additional parameters to enable additional filtering in your UI at support@flowxo.com