> For the complete documentation index, see [llms.txt](https://docs.thryve.health/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.thryve.health/access-data-via-wearable-api/get-ecg-data-beta.md).

# Get ECG data (Beta)

Each electrocardiogram (ECG) recording is stored as a measurement: one recording session with its own start and end time, a unique `reference`, and the voltage waveform of the recording as a health document. The ECG REST-API allows for data retrieval per end user.

There are two endpoints:

| Endpoint                               | Use it to                                                   |
| -------------------------------------- | ----------------------------------------------------------- |
| `POST /data/v6/electrocardiogram/list` | Get all ECG recordings of a user within a time range        |
| `POST /data/v6/electrocardiogram`      | Get one specific ECG recording by its measurement reference |

A typical flow is to call the list endpoint first to find a user's recordings, store each recording's `measurement.reference`, and use it later to fetch that specific recording again with the single ECG endpoint. Additional information, such as the derived heart rate or the recording device, can be added to the response with `additionalDetails`.

### Supported data sources <a href="#user-content-supported-data-sources" id="user-content-supported-data-sources"></a>

| Data source   | Waveform | Heart rate | AFib (atrial fibrillation) |
| ------------- | -------- | ---------- | -------------------------- |
| Apple Health  | ✓        | ✓          | ✓                          |
| Google Health | ✓        | ✓          | ✓                          |
| Withings      | ✓        | ✓          | ✓                          |
| Polar         | ✓        | ✓          | –                          |

{% hint style="warning" %}
ECG data is only retrieved for apps that have the ECG feature enabled. Please reach out to our support team to enable it for your app.
{% endhint %}

## List ECG recordings in a time range

> Looks up the end user by \`endUserId\` (access token) and returns all of their measurements\
> that start within the requested time range, each with its ECG waveform (\`electrocardiogramData\`).\
> Related epochs (e.g. heart rate, AFib) and device data are only returned when requested via\
> \`additionalDetails\`.\
> \
> Rules:\
> \
> \- \`startTimestamp\` and \`endTimestamp\` must use the same format: both UNIX (epoch milliseconds)\
> &#x20; or both ISO-8601.\
> \- The range may be at most 31 days and must not be in the future.\
> \- The lower bound is extended by 24 hours internally, so recordings that started up to\
> &#x20; one day before \`startTimestamp\` can also be returned.\
> \- Results are not ordered and not paginated. If none are found, \`data\` is an empty list.<br>

```json
{"openapi":"3.0.3","info":{"title":"Health Data API – Electrocardiogram","version":"6.0"},"servers":[{"url":"https://api.thryve.de"}],"paths":{"/data/v6/electrocardiogram/list":{"post":{"operationId":"listElectrocardiograms","summary":"List ECG recordings in a time range","description":"Looks up the end user by `endUserId` (access token) and returns all of their measurements\nthat start within the requested time range, each with its ECG waveform (`electrocardiogramData`).\nRelated epochs (e.g. heart rate, AFib) and device data are only returned when requested via\n`additionalDetails`.\n\nRules:\n\n- `startTimestamp` and `endTimestamp` must use the same format: both UNIX (epoch milliseconds)\n  or both ISO-8601.\n- The range may be at most 31 days and must not be in the future.\n- The lower bound is extended by 24 hours internally, so recordings that started up to\n  one day before `startTimestamp` can also be returned.\n- Results are not ordered and not paginated. If none are found, `data` is an empty list.\n","tags":["Health Data"],"parameters":[{"$ref":"#/components/parameters/Authorization"},{"$ref":"#/components/parameters/AppAuthorization"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FindAllMeasurementRequest"}}}},"responses":{"200":{"description":"ECG recordings found (may be an empty list)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EcgListResponse"}}}},"400":{"description":"Invalid request: missing or invalid `startTimestamp` / `endTimestamp` (negative or in the future),\nmixed UNIX and ISO formats, `startTimestamp` after `endTimestamp`, range longer than 31 days,\nunknown `dataSourceIds`, or unreadable JSON.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"`AppAuthorization` header missing or invalid (unknown authID or wrong authSecret).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`endUserId` is unknown or does not belong to the authenticated app.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"415":{"description":"Unsupported media type (body must be `application/json`).","content":{"text/plain":{"schema":{"type":"string"}}}},"429":{"description":"ECG list rate limit for the app exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unhandled error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Data is in cold storage and could not be queried (`ColdTierQueryException`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"Authorization":{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"},"description":"Basic Auth for your username:password. Required for all endpoints."},"AppAuthorization":{"name":"AppAuthorization","in":"header","required":true,"schema":{"type":"string"},"description":"Basic Auth for your authID:authSecret. Required for all endpoints."}},"schemas":{"FindAllMeasurementRequest":{"type":"object","required":["endUserId","startTimestamp","endTimestamp"],"properties":{"endUserId":{"type":"string","description":"End user's access token."},"startTimestamp":{"allOf":[{"$ref":"#/components/schemas/Timestamp"}],"description":"Start of the range (inclusive), as epoch milliseconds or ISO-8601.\nIts format also sets the response's `timestampType`.\n"},"endTimestamp":{"allOf":[{"$ref":"#/components/schemas/Timestamp"}],"description":"End of the range (inclusive). Must use the same format as `startTimestamp`."},"dataSourceIds":{"type":"array","description":"Only return recordings from these Thryve data source IDs. All sources if omitted.","items":{"type":"integer","format":"int32"}},"additionalDetails":{"type":"array","uniqueItems":true,"description":"Optional extras to include in the response:\n- `creationTimestamp` – adds `creationTimestamp` to each measurement (and to each epoch, if `epochData` is requested)\n- `epochData` – adds the epochs linked to each measurement (e.g. heart rate, AFib)\n- `deviceData` – adds the recording device\n- `dataSourceName` – adds `dataSourceName`\n- `endUserAlias` – adds `endUserAlias` (end-user pseudonym)\n","items":{"$ref":"#/components/schemas/AdditionalDetail"}}}},"Timestamp":{"description":"Epoch milliseconds when `timestampType` is `UNIX`, ISO-8601 date-time when `ISO`.","oneOf":[{"type":"integer","format":"int64"},{"type":"string","format":"date-time"}]},"AdditionalDetail":{"type":"string","enum":["creationTimestamp","epochData","deviceData","dataSourceName","endUserAlias"]},"EcgListResponse":{"type":"object","description":"Null fields are omitted.","properties":{"endUserId":{"type":"string","description":"End user's access token."},"endUserAlias":{"type":"string","description":"Only present when `endUserAlias` was requested."},"type":{"type":"string","enum":["response.data.electrocardiogram.list"],"description":"Response type identifier (`ResponseType.ECG_LIST`)."},"timestampType":{"$ref":"#/components/schemas/TimestampType"},"data":{"type":"array","description":"One entry per recording. Empty if none were found.","items":{"$ref":"#/components/schemas/EcgDataSource"}}}},"TimestampType":{"type":"string","enum":["ISO","UNIX"],"description":"Case-insensitive. `UNIX` returns epoch milliseconds plus `timezoneOffset`;\n`ISO` returns ISO-8601 date-times with offset.\n"},"EcgDataSource":{"type":"object","properties":{"dataSourceId":{"type":"integer","format":"int32","description":"Thryve data source ID of the measurement."},"dataSourceName":{"type":"string","description":"Only present when `dataSourceName` was requested."},"measurement":{"$ref":"#/components/schemas/MeasurementValue"},"device":{"$ref":"#/components/schemas/DeviceValue"},"electrocardiogramData":{"$ref":"#/components/schemas/Electrocardiogram"},"epochData":{"type":"array","description":"Only present when `epochData` was requested.","items":{"$ref":"#/components/schemas/EpochValue"}}}},"MeasurementValue":{"type":"object","properties":{"reference":{"type":"integer","format":"int64"},"startTimestamp":{"$ref":"#/components/schemas/Timestamp"},"endTimestamp":{"allOf":[{"$ref":"#/components/schemas/Timestamp"}],"description":"Omitted when the measurement has no end time (e.g. Google Health)."},"timezoneOffset":{"type":"integer","format":"int32","description":"Offset in minutes. Only present for `UNIX`."},"additionalDetails":{"type":"object","description":"Only present when `creationTimestamp` was requested.","properties":{"creationTimestamp":{"$ref":"#/components/schemas/Timestamp"}}}}},"DeviceValue":{"type":"object","description":"Only present when `deviceData` was requested and a device is linked.","properties":{"model":{"type":"string"},"manufacturer":{"type":"string"},"type":{"type":"string"},"serialNumber":{"type":"string"},"firmware":{"type":"string"},"annotation":{"type":"string"}}},"Electrocardiogram":{"type":"object","description":"Omitted if no waveform is stored for the measurement.","properties":{"unit":{"type":"string"},"samplingFrequencyHz":{"type":"integer","format":"int32"},"leads":{"$ref":"#/components/schemas/Leads"}}},"Leads":{"type":"object","description":"Only leads with stored data are present. Wearables usually provide lead `I` only.","properties":{"I":{"$ref":"#/components/schemas/Lead"},"II":{"$ref":"#/components/schemas/Lead"},"III":{"$ref":"#/components/schemas/Lead"},"aVL":{"$ref":"#/components/schemas/Lead"},"aVR":{"$ref":"#/components/schemas/Lead"},"aVF":{"$ref":"#/components/schemas/Lead"},"V1":{"$ref":"#/components/schemas/Lead"},"V2":{"$ref":"#/components/schemas/Lead"},"V3":{"$ref":"#/components/schemas/Lead"},"V4":{"$ref":"#/components/schemas/Lead"},"V5":{"$ref":"#/components/schemas/Lead"},"V6":{"$ref":"#/components/schemas/Lead"}}},"Lead":{"type":"array","description":"Voltage samples in `unit`, in recording order at `samplingFrequencyHz`.","items":{"type":"number","format":"double"}},"EpochValue":{"type":"object","properties":{"startTimestamp":{"$ref":"#/components/schemas/Timestamp"},"endTimestamp":{"$ref":"#/components/schemas/Timestamp"},"timezoneOffset":{"type":"integer","format":"int32"},"dataTypeId":{"type":"integer","format":"int32"},"value":{"type":"string"},"additionalDetails":{"$ref":"#/components/schemas/EpochAdditionalDetails"}}},"EpochAdditionalDetails":{"type":"object","description":"Only present when `creationTimestamp` was requested.","properties":{"creationTimestamp":{"$ref":"#/components/schemas/Timestamp"}}},"ErrorResponse":{"type":"object","properties":{"timestamp":{"type":"integer","format":"int64"},"status":{"type":"integer"},"error":{"type":"string"},"path":{"type":"string"},"traceId":{"type":"string"}}}}}}
```

## Get one ECG recording by measurement reference

> Looks up the end user by \`endUserId\` (access token), loads the measurement\
> identified by \`measurementReference\`, and always includes its ECG waveform\
> (\`electrocardiogramData\`). \
> \
> Related epochs (e.g. heart rate, AFib) and device data are\
> only returned when requested via \`additionalDetails\`.<br>

```json
{"openapi":"3.0.3","info":{"title":"Health Data API – Electrocardiogram","version":"6.0"},"servers":[{"url":"https://api.thryve.de"}],"paths":{"/data/v6/electrocardiogram":{"post":{"operationId":"getElectrocardiogram","summary":"Get one ECG recording by measurement reference","description":"Looks up the end user by `endUserId` (access token), loads the measurement\nidentified by `measurementReference`, and always includes its ECG waveform\n(`electrocardiogramData`). \n\nRelated epochs (e.g. heart rate, AFib) and device data are\nonly returned when requested via `additionalDetails`.\n","tags":["Health Data"],"parameters":[{"$ref":"#/components/parameters/Authorization"},{"$ref":"#/components/parameters/AppAuthorization"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FindMeasurementDataRequest"}}}},"responses":{"200":{"description":"ECG recording found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EcgResponse"}}}},"400":{"description":"Invalid request: missing `measurementReference` (\"missing mandatory measurementReference\"),\nunreadable JSON, invalid `timestampType`, or\nmeasurement reference not found for this end user (`MissingDataException`).\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"`AppAuthorization` header missing or invalid (unknown authID or wrong authSecret).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`endUserId` is unknown or does not belong to the authenticated app.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"415":{"description":"Unsupported media type (body must be `application/json`).","content":{"text/plain":{"schema":{"type":"string"}}}},"429":{"description":"ECG rate limit for the app exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unhandled error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Data is in cold storage and could not be queried (`ColdTierQueryException`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"Authorization":{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"},"description":"Basic Auth for your username:password. Required for all endpoints."},"AppAuthorization":{"name":"AppAuthorization","in":"header","required":true,"schema":{"type":"string"},"description":"Basic Auth for your authID:authSecret. Required for all endpoints."}},"schemas":{"FindMeasurementDataRequest":{"type":"object","required":["endUserId","measurementReference","timestampType"],"properties":{"endUserId":{"type":"string","description":"End user's access token (mapped to `accessToken` in code)."},"measurementReference":{"type":"integer","format":"int64","description":"Reference of the ECG measurement, as stored by the consumer service."},"timestampType":{"$ref":"#/components/schemas/TimestampType"},"additionalDetails":{"type":"array","uniqueItems":true,"description":"Optional extras to include in the response:\n- `creationTimestamp` – adds `creationTimestamp` to the measurement (and to each epoch, if `epochData` is requested)\n- `epochData` – adds the epochs linked to the measurement (e.g. heart rate, AFib)\n- `deviceData` – adds the recording device\n- `dataSourceName` – adds `dataSourceName`\n- `endUserAlias` – adds `endUserAlias` (end-user pseudonym)\n","items":{"$ref":"#/components/schemas/AdditionalDetail"}}}},"TimestampType":{"type":"string","enum":["ISO","UNIX"],"description":"Case-insensitive. `UNIX` returns epoch milliseconds plus `timezoneOffset`;\n`ISO` returns ISO-8601 date-times with offset.\n"},"AdditionalDetail":{"type":"string","enum":["creationTimestamp","epochData","deviceData","dataSourceName","endUserAlias"]},"EcgResponse":{"type":"object","description":"Null fields are omitted. Note: unlike the list endpoint, this single-recording response\ndoes not set `timestampType`.\n","properties":{"endUserId":{"type":"string","description":"End user's access token."},"endUserAlias":{"type":"string","description":"Only present when `endUserAlias` was requested."},"type":{"type":"string","enum":["response.data.electrocardiogram"],"description":"Response type identifier (`ResponseType.ECG`)."},"data":{"type":"array","description":"Always exactly one entry.","minItems":1,"maxItems":1,"items":{"$ref":"#/components/schemas/EcgDataSource"}}}},"EcgDataSource":{"type":"object","properties":{"dataSourceId":{"type":"integer","format":"int32","description":"Thryve data source ID of the measurement."},"dataSourceName":{"type":"string","description":"Only present when `dataSourceName` was requested."},"measurement":{"$ref":"#/components/schemas/MeasurementValue"},"device":{"$ref":"#/components/schemas/DeviceValue"},"electrocardiogramData":{"$ref":"#/components/schemas/Electrocardiogram"},"epochData":{"type":"array","description":"Only present when `epochData` was requested.","items":{"$ref":"#/components/schemas/EpochValue"}}}},"MeasurementValue":{"type":"object","properties":{"reference":{"type":"integer","format":"int64"},"startTimestamp":{"$ref":"#/components/schemas/Timestamp"},"endTimestamp":{"allOf":[{"$ref":"#/components/schemas/Timestamp"}],"description":"Omitted when the measurement has no end time (e.g. Google Health)."},"timezoneOffset":{"type":"integer","format":"int32","description":"Offset in minutes. Only present for `UNIX`."},"additionalDetails":{"type":"object","description":"Only present when `creationTimestamp` was requested.","properties":{"creationTimestamp":{"$ref":"#/components/schemas/Timestamp"}}}}},"Timestamp":{"description":"Epoch milliseconds when `timestampType` is `UNIX`, ISO-8601 date-time when `ISO`.","oneOf":[{"type":"integer","format":"int64"},{"type":"string","format":"date-time"}]},"DeviceValue":{"type":"object","description":"Only present when `deviceData` was requested and a device is linked.","properties":{"model":{"type":"string"},"manufacturer":{"type":"string"},"type":{"type":"string"},"serialNumber":{"type":"string"},"firmware":{"type":"string"},"annotation":{"type":"string"}}},"Electrocardiogram":{"type":"object","description":"Omitted if no waveform is stored for the measurement.","properties":{"unit":{"type":"string"},"samplingFrequencyHz":{"type":"integer","format":"int32"},"leads":{"$ref":"#/components/schemas/Leads"}}},"Leads":{"type":"object","description":"Only leads with stored data are present. Wearables usually provide lead `I` only.","properties":{"I":{"$ref":"#/components/schemas/Lead"},"II":{"$ref":"#/components/schemas/Lead"},"III":{"$ref":"#/components/schemas/Lead"},"aVL":{"$ref":"#/components/schemas/Lead"},"aVR":{"$ref":"#/components/schemas/Lead"},"aVF":{"$ref":"#/components/schemas/Lead"},"V1":{"$ref":"#/components/schemas/Lead"},"V2":{"$ref":"#/components/schemas/Lead"},"V3":{"$ref":"#/components/schemas/Lead"},"V4":{"$ref":"#/components/schemas/Lead"},"V5":{"$ref":"#/components/schemas/Lead"},"V6":{"$ref":"#/components/schemas/Lead"}}},"Lead":{"type":"array","description":"Voltage samples in `unit`, in recording order at `samplingFrequencyHz`.","items":{"type":"number","format":"double"}},"EpochValue":{"type":"object","properties":{"startTimestamp":{"$ref":"#/components/schemas/Timestamp"},"endTimestamp":{"$ref":"#/components/schemas/Timestamp"},"timezoneOffset":{"type":"integer","format":"int32"},"dataTypeId":{"type":"integer","format":"int32"},"value":{"type":"string"},"additionalDetails":{"$ref":"#/components/schemas/EpochAdditionalDetails"}}},"EpochAdditionalDetails":{"type":"object","description":"Only present when `creationTimestamp` was requested.","properties":{"creationTimestamp":{"$ref":"#/components/schemas/Timestamp"}}},"ErrorResponse":{"type":"object","properties":{"timestamp":{"type":"integer","format":"int64"},"status":{"type":"integer"},"error":{"type":"string"},"path":{"type":"string"},"traceId":{"type":"string"}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.thryve.health/access-data-via-wearable-api/get-ecg-data-beta.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
