# Fetch journey analytics records

Source: https://govform.com/resources/documentation/article/33-03-api-fetch-journey-analytics
Topic: Govform API & MCP

**API units: 5 or 25.** A page of up to 100 records uses 5 units. A page over 100 records uses 25 units. The default page size is 1,000, so a request without a page size uses 25 units.

This endpoint fetches analytics data on a per-journey basis. One record is returned per user journey, each of which may or may not yet be complete.

Data can be returned in JSON or CSV format. The columns in the CSV are fixed; not all values will be set for all events as some columns are specific to one event type.

Use the query parameters to filter the results by **journey end** date/time. Note some journeys span multiple days, and journeys from previous days may change if the user continues them into the next day, thus causing them to appear in the next days journey data. This is more of a concern for large authenticated services supporting save & come back later, than it is for smaller anonymous services that must be completed in one sitting.

Results are paginated, meaning the API endpoint will provide the first page of results along with the number of pages. Your application can then call the endpoint again to retrieve subsequent results pages.

## Endpoint and parameters

```
GET /api/analytics-journeys/{libraryId}/{serviceId}
```

| Parameter | Description | Mandatory |
| --- | --- | --- |
| **libraryId** | The ID of the library of the service from which to retrieve journey analytics | yes |
| **serviceId** | The service ID of the service from which to retrieve journey analytics | yes |

### Query parameters

| Parameter | Description | Mandatory |
| --- | --- | --- |
| **format** | The output format to use in the response body, set to _json_ or _csv_ | yes |
| **fromDate** | The first event date to return data for (inclusive), in the format yyyy-mm-dd | yes |
| **toDate** | The last event date to return data for (inclusive), in the format yyyy-mm-dd | yes |
| **hour** | Restrict the result to one completed hour (0–23). Use only when `fromDate` and `toDate` are the same. For today, the hour must be earlier than the current hour. If omitted for today, Govform returns data only up to the start of the current hour. | no |
| **page** | The page of results to fetch. If omitted, page 1 is assumed. The response body will include the number of pages to fetch; if over 1 then the endpoint should be called again with this parameter set to each subsequent page number to retrieve all result pages. | no |
| **pageSize** | Number of results per page, from 1 to 1000. Defaults to 1000; larger values are capped at 1000. | no |
| **submissionRef** | If specified, only events for the specified submission reference will be returned. | no |
| **csvHeader** | If format is set to _csv_, this parameter controls the header row to output. Set to _on_ to include field names in the header row. Set to _none_ to not include a header row in the output. Defaults to _on_. | no |
| **csvHeaderFields** | If format is set to _csv_, optionally set this to specify which fields should be included in the output, separated by commas. The provided values are compared against the CSV header titles for each field and so depend upon the _csvHeader_ setting. The provided field columns will always be present in the order specified and no additional columns will be added. | no |
| **excelMode** | If format is set to _csv_, set this to _on_ to wrap all values that are under 200 characters in ="_value_" to prevent Excel from attempting to auto-transform numbers and dates. For raw CSV feeds not intended for display in Excel, set to _off_. Defaults to _off_. | no |

**Authentication:** send `GovformsApiKey <key-id>:<key-secret>` in the `Authorization` header. Substitute credentials from your secrets manager; never copy a live key into documentation, source control or logs.

## Examples

Request Headers

| Header name | value |
| --- | --- |
| Authorization | GovformsApiKey <key-id>:<key-secret> |

**JSON mode example:**

Request URL

```
GET https://qa.cloud.govforms.uk/api/analytics-journeys/demo-library/demo-service-1?format=json&fromDate=2023-03-18&toDate=2023-03-18
```

  Response Headers

| Header name | value |
| --- | --- |
| Content-Type | application/json |

Response body

```
{
  "totalResults": 1,
  "totalResultsPages": 1,
  "resultsPage": 1,
  "results": [
    {
      "submissionId": "PGEE-EE2H-3Y67",
      "userId": "anon-c2305120-1a15-441d-90a8-b4246a9b8e71",
      "userEmail": null,
      "journeyStart": "2023-03-17T23:57:53.249+00:00",
      "journeyEnd": "2023-03-18T00:02:41.267+00:00",
      "journeyDayOfWeek": 6,
      "timeSpentOnPages": [
        {
          "pageNum": 1,
          "pageName": "About this service",
          "timeSpentSeconds": 0.909
        },
        {
          "pageNum": 2,
          "pageName": "Do you meet the requirements for this form?",
          "timeSpentSeconds": 35.86
        },
        {
          "pageNum": 3,
          "pageName": "You cannot continue if you do not meet the requirements",
          "timeSpentSeconds": 1200
        }
      ],
      "activeTimeInJourneySeconds": 1236.769,
      "isComplete": false,
      "numSuccessPageHits": 4,
      "numErrorPageHits": 0,
      "dropOutPageName": "You cannot continue if you do not meet the requirements",
      "dropOutPageNum": 3,
      "dropOutPageType": "exitPage",
      "validationErrors": [],
      "userAgentDetails": {
        "browser": {
          "name": "Microsoft Edge",
          "version": "110.0.1587.41"
        },
        "os": {
          "name": "Windows",
          "version": "NT 10.0",
          "versionName": "10"
        },
        "platform": {
          "type": "desktop"
        },
        "engine": {
          "name": "Blink"
        }
      },
      "taggedFieldData": {
        "doYouMeetTheRequirementsForThisForm": "No"
      }
    }
  ]
}
```

**CSV mode example:** Request URL

```
GET https://qa.cloud.govforms.uk/api/analytics-journeys/demo-library/demo-service-1?format=csv&fromDate=2023-03-18&toDate=2023-03-18
```

  Response headers

| Header name | value |
| --- | --- |
| Content-Type | text/csv |
| Govforms-Total-Results | 1 |
| Govforms-Total-Results-Pages | 1 |
| Govforms-Results-Page | 1 |

Response body

```
"submissionId","userId","userEmail","journeyStart","journeyEnd","journeyDayOfWeek","timeSpentOnPages-pageNum","timeSpentOnPages-pageName","timeSpentOnPages-timeSpentSeconds","activeTimeInJourneySeconds","isComplete","activeTimeInJourneySeconds", "isComplete", "numSuccessPageHits", "numErrorPageHits", "dropOutPageName", "dropOutPageNum", "dropOutPageType","validationErrors-timestamp","validationErrors-pageNum","userAgentDetails-browser-name","userAgentDetails-browser-version","userAgentDetails-os-name","userAgentDetails-os-version","userAgentDetails-os-versionName","userAgentDetails-platform-type","userAgentDetails-engine-name","taggedFieldData-fieldId","taggedFieldData-fieldValue"
"PGEE-EE2H-3Y67","anon-c2305120-1a15-441d-90a8-b4246a9b8e71",null,"2023-03-17T23:57:53.249+00:00","2023-03-18T00:02:41.267+00:00","6","1|2|3","About this service|Do you meet the requirements for this form?|You cannot continue if you do not meet the requirements","0.909|35.86|1200","1236.769","false","1236.769","false","4","0","You cannot continue if you do not meet the requirements","3","exitPage","","","Microsoft Edge","110.0.1587.41","Windows","NT 10.0","10","desktop","Blink","doYouMeetTheRequirementsForThisForm","No"
```

* * *