Reports API

Authorization

Include Authorization: Bearer <apikey> header in your requests.

Error handling

Every request can return an error in its context:

{
  "result": "error|fail",
  "message": "Title is not set or is too short"
}

Get possible reports list

Request: GET https://bottalk.io/api/reports

Response:

{
  "result": "ok",
  "reports": [
    {
      "name": "AvgListen",
      "title": "Average Listen Report",
      "params": {
        "date_start": "today",
        "date_end": "tomorrow"
      },
      "columns": {
        "d": "Date",
        "vg": "Average Listen Length (% of article)",
        "project_id": "Project"
      }
    },
    {
      "name": "ActiveUsers",
      "title": "Playback Started Report",
      "params": {
        "date_start": "today",
        "date_end": "tomorrow"
      },
      "columns": {
        "d": "Date",
        "au": "Active Users",
        "project_id": "Project"
      }
    },
    {
      "name": "UniqueShows",
      "title": "Unique Shows Report",
      "params": {
        "date_start": "today",
        "date_end": "tomorrow"
      },
      "columns": {
        "d": "Date",
        "imp": "Unique Users",
        "project_id": "Project"
      }
    },
    {
      "name": "CTR",
      "title": "CTR Report",
      "params": {
        "date_start": "today",
        "date_end": "tomorrow"
      },
      "columns": {
        "d": "Date",
        "imp": "Impressions",
        "au": "Clicks",
        "ctr": "CTR",
        "project_id": "Project"
      }
    },
    {
      "name": "UsersMoreThanTime",
      "title": "UsersMoreThanTime Report",
      "params": {
        "date_start": "today",
        "date_end": "tomorrow",
        "time": 60
      },
      "columns": {
        "d": "Date",
        "nu": "Number of users",
        "perc": "Percent of users",
        "project_id": "Project"
      }
    },
    {
      "name": "UsersMoreThan",
      "title": "UsersMoreThan Report",
      "params": {
        "date_start": "today",
        "date_end": "tomorrow",
        "percent": 50
      },
      "columns": {
        "d": "Date",
        "nu": "Number of users",
        "perc": "Percent of users",
        "project_id": "Project"
      }
    },
    {
      "name": "CohortListenPercent",
      "title": "Cohort average listeners report",
      "params": {
        "date_start": "today",
        "date_end": "tomorrow"
      },
      "columns": {
        "p": "Percent of article",
        "users": "Number of Users",
        "percent": "Percent of Users",
        "project_id": "Project"
      }
    },
    {
      "name": "PopularArticles",
      "title": "Popular Articles Report",
      "params": {
        "date_start": "today",
        "date_end": "tomorrow"
      },
      "columns": {
        "cnt": "Number of listeners",
        "title": "Title"
      }
    },
    {
      "name": "CohortArticles",
      "title": "Cohort Articles Report",
      "params": {
        "date_start": "today",
        "date_end": "tomorrow"
      },
      "columns": {
        "cnt": "Number of listeners",
        "title": "Title"
      }
    }
  ]
}

Get a single report

Request: GET https://bottalk.io/api/reports/{name}?param1=value&param2=value2

Response:

{
  "result": "ok",
  "headers": {
    "p": "Percent of article",
    "users": "Number of Users",
    "percent": "Percent of Users",
    "project_id": "Project"
  },
  "title": "Users listening more than X% of article (2019-12-09 00:00:00 - 2019-12-10 23:59:59)",
  "report": [
    {
      "p": 0,
      "users": 0,
      "percent": "0%",
      "project_id": "My test project"
    },
    {
      "p": 10,
      "users": 0,
      "percent": "0%",
      "project_id": "My test project"
    },
    {
      "p": 20,
      "users": 0,
      "percent": "0%",
      "project_id": "My test project"
    },
    {
      "p": 30,
      "users": 0,
      "percent": "0%",
      "project_id": "My test project"
    },
    {
      "p": 40,
      "users": 0,
      "percent": "0%",
      "project_id": "My test project"
    },
    {
      "p": 50,
      "users": 0,
      "percent": "0%",
      "project_id": "My test project"
    },
    {
      "p": 60,
      "users": 0,
      "percent": "0%",
      "project_id": "My test project"
    },
    {
      "p": 70,
      "users": 0,
      "percent": "0%",
      "project_id": "My test project"
    },
    {
      "p": 80,
      "users": 0,
      "percent": "0%",
      "project_id": "My test project"
    },
    {
      "p": 90,
      "users": 0,
      "percent": "0%",
      "project_id": "My test project"
    },
    {
      "p": 100,
      "users": 0,
      "percent": "0%",
      "project_id": "My test project"
    }
  ]
}