Product Updates | Contact Support | System Status
Page Contents

    Accessing Reporting Endpoints Programmatically

    This topic provides details for how to access reporting data programmatically.

    HapYak provides programmatic access to the reporting data shown in the Studio Reports user interface. This document provides details on how to access the API containing that data from a server-side process like Python or cURL.

    The basics

    The reporting API requires that you pass a valid HapYak reporting API Key associated with your account. API Keys must be passed in the request header X-Hapyak-API-Key. For example:

    X-Hapyak-API-Key: 1e7bc263e32198e49c

    You can find your own reporting API key on the integrations tab of the admin section of the HapYak Portal. Treat your reporting API key with the sensitivity of a password as anyone with it can use it to retrieve reporting data from your account.

    Base URL for reporting requests:

    https://www.hapyak.com/api/reports/v2/

    Example URL structure:

    https://[base-url]/[report-name]?send_status=true&[parameters]

    API request construction

    The API is invoked via GET operation to the Base API URL. The request must contain a valid X-Hapyak-API-Key header. Specific reports are requested by appending the name of the report and valid parameters to the Base API URL.

    Results are not synchronously returned. The reporting API operation is asynchronous in that results may not be available when your request returns. In this case your request will be queued and you will need to poll, or try later, for results.

    Requests must always include send_status=true which forces the API to return HTTP 202 status while the reporting request is processing and then HTTP 200 with results when it is complete.

    To determine if you need to "poll" for results, examine the HTTP status code returned by the API. If it is "202 Accepted" your report is still being generated and you’ll need to repeat the request a little bit later to retrieve results. The results are returned with an HTTP 200 status code when they are complete. Once complete, reporting results are cached for one day and are returned immediately with each request.

    Report endpoints

    The following reports are available via API.

    Name Description End Point
    Project Summary One row per Project project_engagement_summary_raw
    User Summary One row per User user_engagement_summary_raw
    Experience Summary One row per Experience experience_engagement_summary_raw
    Poll Widget Summary

    One row per Poll Widget instance, per poll_widget_summary response value with count of response values.

    Project IDs will contain a list of all projects where the poll appeared and was submitted. This is included to support templates where the same poll widget will appear with multiple projects.

    Note: The Project IDs list is not de-duped.

    poll_widget_summary
    Sign In Widget Summary

    One row per Sign In Widget instance with counts of various Sign In stats. Project IDs will contain a list of all projects where the Sign In appeared and was submitted. This is included to support templates where the same Sign In widget will appear with multiple projects.

    Note: The Project IDs list is not de-duped.

    signin_widget_summary
    User Activity Stream

    One row per Action, with User ID if known

    *Includes "views" of bookmarks, user interactions with player controls, annotations and widgets.

    **Excludes "progress" events.

    user_stream_raw
    Project Activity Stream

    One row per Action

    *Includes "views" of bookmarks, user interactions with player controls, annotations and widgets.

    **Excludes "progress" events.

    project_stream_raw
    Experience Stream

    One row per Action

    *Includes "views" of bookmarks, user interactions with player controls, annotations and widgets.

    **Excludes "progress" events.

    experience_stream_raw
    Poll Widget Detail One row per poll submit event. poll_widget_detail
    Sign In Widget Detail One row per Sign In submit event. Includes events where the user was silently signed-in (auto) because of a previous sign-in (manual). signin_widget_detail

    Report parameters

    All report end_points accept the following parameters:

    start

    Start date for report results. Default value is 7 days before "end" date. Format for dates is YYYY-MM-DD. All times are UTC.

    end

    End date for report results. Default value is end of current day. For example if today is 2021-09-23, the default end date is 2021-09-23 23:59:59.999.

    format

    Output format for report results. Supported values are: csv and json.

    send_status

    For easier interaction with the API we suggest that you always include send_status=true. This forces the API to return HTTP 202 status while the reporting request is processing and then HTTP 200 with results when it is complete.

    Important details: limits

    • Maximum row count - The API limits the returned results to 500,000 rows of output. Output beyond this limit is omitted from the results.
    • Maximum time range - The API limits the time range of data retrieved to six months.
    • Rate limits - By default, the reporting API limits you to running 4 reports per minute; 20 per hour; and 100 per day. These limits apply to the number of unique reports you can execute, not the number of times you hit the reporting endpoint to retrieve results or check status on an already queued report.

    Python code example

    The example below illustrates how to invoke a report from Python using the popular Requests library.

    import requests
    import sys
    import time
    
    TIMEOUT = 120 # consider a report “timed out” if running > 2
    
    minutes processing = True
    
    url = "https://www.hapyak.com/api/reports/v2/project_engagement_summary_raw"
    
    # Reporting endpoint url
    
    querystring = {
        "start": "2019-07-01", # begin date
        "end": "2019-09-30", # end date
        "format": "csv", # csv or JSON
        "send_status":"true"
        }
    headers = {
        'X-Hapyak-API-Key': "YOUR-KEY-HERE",
        'cache-control': "no-cache",
        }
    
    start_time = time.time()
    
    while processing:
        if time.time() - start_time > TIMEOUT:
            print('Report timed-out') 
            sys.exit(-1) 
    response = requests.request("GET", url, headers=headers, params=querystring) print('Result: {}'.format(response.status_code)) 
    if response.status_code == 200: 
        processing = False 
        print(response.text) 
    elif response.status_code == 202: 
        print('sleep/recheck') 
        time.sleep (10) 
    else: 
        print('Something went wrong') 
        sys.exit(-2)
        

    Page last updated on 27 Jun 2022