> For the complete documentation index, see [llms.txt](https://docs.tryterra.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tryterra.co/reference/health-and-fitness-api/user.md).

# User

Look up connected users by user ID or your own reference ID.

## Get user info by user ID or reference ID

> Returns one user by \`user\_id\`, or every user registered under a \`reference\_id\`.\
> \
> \- A \`user\_id\` request returns the user under \`user\`; a \`reference\_id\` request returns a \`users\` list.\
> \- Sending neither parameter returns \`404\`.\
> \- A \`reference\_id\` that matches no user returns an empty \`users\` list, not \`404\`.

```json
{"openapi":"3.2.0","info":{"title":"Terra API","version":"2026.11.19"},"tags":[{"name":"User","summary":"User","description":"Look up connected users by user ID or your own reference ID."}],"servers":[{"url":"https://access.tryterra.co/api/v2"}],"security":[{"ApiKeyAuth":[],"DevID":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key for authentication"},"DevID":{"type":"apiKey","in":"header","name":"dev-id","description":"Your developer ID for authentication and tracking"}},"schemas":{"UserWithPolling":{"description":"A user with the times Terra last polled their provider and last received data for them. Each is null when Terra has no such time, and both are left out for a user that is not a provider connection.","allOf":[{"$ref":"#/components/schemas/TerraUser"},{"type":"object","properties":{"last_polled_at":{"type":["string","null"],"format":"date-time","description":"Last time Terra polled the provider for this connection."},"most_recent_data_at":{"type":["string","null"],"format":"date-time","description":"Timestamp of the most recent data point Terra holds for this connection."}}}]},"TerraUser":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"user_id":{"type":"string","minLength":1,"description":"Terra identifier for the wearable connection"},"provider":{"type":"string","minLength":1,"description":"Connection data source"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Time at which the connection was created"},"last_webhook_update":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Last time at which a webhook update was sent for the connection"},"scopes":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"(when available) Permissions granted by the user during authentication - to be used as debugging metadata"},"reference_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Connection identifier on the developer's end, used to tie connection back to a user on the developer's platform"},"active":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"whether the user is active or not (inactive users will not receive any data updates and are in considered "}},"required":["user_id","provider"]},"Problem":{"type":"object","description":"An error response, following RFC 9457 (Problem Details for HTTP APIs, which obsoletes RFC 7807). Returned with `Content-Type: application/problem+json` on every 4xx/5xx response. The HTTP status line carries the status code; it is intentionally not repeated in the body. `type`, `title` and `instance` are always present; `detail` is included when a specific explanation is available.\n","properties":{"type":{"type":"string","description":"A URI reference identifying the problem type. Defaults to `about:blank`."},"title":{"type":"string","description":"A short, human-readable summary of the problem type (the lowercased HTTP status text)."},"instance":{"type":"string","description":"The request path, including any query string, that produced this problem."},"code":{"type":"string","description":"Stable error classification: branch on this, not on `detail`. A refused credential returns unauthorized (401: missing, invalid, expired or revoked), scope_missing (403: the credential lacks the scope the operation requires) or audience_restricted (403: the credential is not granted for this dev-id). authorization_unavailable (503) means the credential or the product access could not be checked; retry later. Product gates return entitlement_required (403) or environment_disabled (403). service_unavailable (503) means the request never reached the service; dependency_failed (502 or 504) means the service did not complete it, though it may already have acted on it. Report uploads return validation_failed, unsupported_file_type or too_many_files (400), payload_too_large (413) and rate_limited (429)."},"product":{"type":"string","description":"The product checked by the authorization gate, when classified."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["type","title","instance"]},"UnauthorizedProblem":{"type":"object","description":"A refused credential, always with its code.","properties":{"type":{"type":"string","description":"A URI reference identifying the problem type. Defaults to `about:blank`."},"title":{"type":"string","description":"A short, human-readable summary of the problem type (the lowercased HTTP status text)."},"instance":{"type":"string","description":"The request path, including any query string, that produced this problem."},"code":{"type":"string","description":"Stable error classification: branch on this, not on `detail`. A refused credential returns unauthorized (401: missing, invalid, expired or revoked), scope_missing (403: the credential lacks the scope the operation requires) or audience_restricted (403: the credential is not granted for this dev-id). authorization_unavailable (503) means the credential or the product access could not be checked; retry later. Product gates return entitlement_required (403) or environment_disabled (403). service_unavailable (503) means the request never reached the service; dependency_failed (502 or 504) means the service did not complete it, though it may already have acted on it. Report uploads return validation_failed, unsupported_file_type or too_many_files (400), payload_too_large (413) and rate_limited (429)."},"product":{"type":"string","description":"The product checked by the authorization gate, when classified."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["type","title","instance","code"]}},"responses":{"BadRequest":{"description":"One or more parameters is malformed. The `detail` field describes the specific problem.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"Unauthorized":{"description":"The credential is missing, invalid, expired or revoked (code `unauthorized`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/UnauthorizedProblem"}}}},"NotFound":{"description":"A referenced resource does not exist on Terra's end.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"AuthorizationUnavailable":{"description":"The credential or the product access could not be checked (code `authorization_unavailable`). Retry after the service recovers.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"paths":{"/userInfo":{"get":{"tags":["User"],"operationId":"User_Get","description":"Returns one user by `user_id`, or every user registered under a `reference_id`.\n\n- A `user_id` request returns the user under `user`; a `reference_id` request returns a `users` list.\n- Sending neither parameter returns `404`.\n- A `reference_id` that matches no user returns an empty `users` list, not `404`.","summary":"Get user info by user ID or reference ID","parameters":[{"name":"user_id","in":"query","description":"Terra user ID of the user to return. Takes precedence over `reference_id` when both are sent.","schema":{"type":"string"},"required":false},{"name":"reference_id","in":"query","description":"Your identifier for the end user; every user registered under it is returned.","schema":{"type":"string"},"required":false}],"responses":{"200":{"description":"Returned when the provided resources are found","content":{"application/json":{"schema":{"oneOf":[{"title":"By user ID","description":"Returned for a `user_id` request.","type":"object","required":["status","is_authenticated","user"],"properties":{"status":{"type":"string","enum":["success"],"default":"success"},"is_authenticated":{"type":"boolean","description":"Always `true`."},"user":{"$ref":"#/components/schemas/UserWithPolling"}}},{"title":"By reference ID","description":"Returned for a `reference_id` request without `user_id`.","type":"object","required":["status","users"],"properties":{"status":{"type":"string","enum":["success"],"default":"success"},"users":{"type":"array","description":"Every user registered under the reference ID; empty when none matches.","items":{"$ref":"#/components/schemas/UserWithPolling"}}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"503":{"$ref":"#/components/responses/AuthorizationUnavailable"}}}}}}
```

## List all user IDs

> Lists every user in your environment, either in one response or a page at a time.

```json
{"openapi":"3.2.0","info":{"title":"Terra API","version":"2026.11.19"},"tags":[{"name":"User","summary":"User","description":"Look up connected users by user ID or your own reference ID."}],"servers":[{"url":"https://access.tryterra.co/api/v2"}],"security":[{"ApiKeyAuth":[],"DevID":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key for authentication"},"DevID":{"type":"apiKey","in":"header","name":"dev-id","description":"Your developer ID for authentication and tracking"}},"schemas":{"TerraUser":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"user_id":{"type":"string","minLength":1,"description":"Terra identifier for the wearable connection"},"provider":{"type":"string","minLength":1,"description":"Connection data source"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Time at which the connection was created"},"last_webhook_update":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Last time at which a webhook update was sent for the connection"},"scopes":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"(when available) Permissions granted by the user during authentication - to be used as debugging metadata"},"reference_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Connection identifier on the developer's end, used to tie connection back to a user on the developer's platform"},"active":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"whether the user is active or not (inactive users will not receive any data updates and are in considered "}},"required":["user_id","provider"]},"Problem":{"type":"object","description":"An error response, following RFC 9457 (Problem Details for HTTP APIs, which obsoletes RFC 7807). Returned with `Content-Type: application/problem+json` on every 4xx/5xx response. The HTTP status line carries the status code; it is intentionally not repeated in the body. `type`, `title` and `instance` are always present; `detail` is included when a specific explanation is available.\n","properties":{"type":{"type":"string","description":"A URI reference identifying the problem type. Defaults to `about:blank`."},"title":{"type":"string","description":"A short, human-readable summary of the problem type (the lowercased HTTP status text)."},"instance":{"type":"string","description":"The request path, including any query string, that produced this problem."},"code":{"type":"string","description":"Stable error classification: branch on this, not on `detail`. A refused credential returns unauthorized (401: missing, invalid, expired or revoked), scope_missing (403: the credential lacks the scope the operation requires) or audience_restricted (403: the credential is not granted for this dev-id). authorization_unavailable (503) means the credential or the product access could not be checked; retry later. Product gates return entitlement_required (403) or environment_disabled (403). service_unavailable (503) means the request never reached the service; dependency_failed (502 or 504) means the service did not complete it, though it may already have acted on it. Report uploads return validation_failed, unsupported_file_type or too_many_files (400), payload_too_large (413) and rate_limited (429)."},"product":{"type":"string","description":"The product checked by the authorization gate, when classified."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["type","title","instance"]},"UnauthorizedProblem":{"type":"object","description":"A refused credential, always with its code.","properties":{"type":{"type":"string","description":"A URI reference identifying the problem type. Defaults to `about:blank`."},"title":{"type":"string","description":"A short, human-readable summary of the problem type (the lowercased HTTP status text)."},"instance":{"type":"string","description":"The request path, including any query string, that produced this problem."},"code":{"type":"string","description":"Stable error classification: branch on this, not on `detail`. A refused credential returns unauthorized (401: missing, invalid, expired or revoked), scope_missing (403: the credential lacks the scope the operation requires) or audience_restricted (403: the credential is not granted for this dev-id). authorization_unavailable (503) means the credential or the product access could not be checked; retry later. Product gates return entitlement_required (403) or environment_disabled (403). service_unavailable (503) means the request never reached the service; dependency_failed (502 or 504) means the service did not complete it, though it may already have acted on it. Report uploads return validation_failed, unsupported_file_type or too_many_files (400), payload_too_large (413) and rate_limited (429)."},"product":{"type":"string","description":"The product checked by the authorization gate, when classified."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["type","title","instance","code"]}},"responses":{"BadRequest":{"description":"One or more parameters is malformed. The `detail` field describes the specific problem.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"Unauthorized":{"description":"The credential is missing, invalid, expired or revoked (code `unauthorized`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/UnauthorizedProblem"}}}},"AuthorizationUnavailable":{"description":"The credential or the product access could not be checked (code `authorization_unavailable`). Retry after the service recovers.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"paths":{"/subscriptions":{"get":{"tags":["User"],"operationId":"User_List","description":"Lists every user in your environment, either in one response or a page at a time.","summary":"List all user IDs","parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Zero-based page number. Omit it to get every user in one unpaginated response; an invalid or negative value is treated as `0`."},{"name":"per_page","in":"query","required":false,"schema":{"type":"integer"},"description":"Users per page when `page` is sent. Defaults to 500, which is also used for an invalid or non-positive value."}],"responses":{"200":{"description":"Returned upon a successful request","content":{"application/json":{"schema":{"type":"object","description":"If `page` is omitted, `users` contains every user. If `page` is provided, `results`, `max_page`, and `next` contain the paginated response.","properties":{"status":{"type":"string","enum":["success"],"default":"success"},"users":{"type":"array","items":{"$ref":"#/components/schemas/TerraUser"}},"next":{"type":["integer","null"],"description":"The next page number, or null if there is no next page"},"max_page":{"type":"integer","description":"Total number of pages available for the requested page size"},"results":{"type":"array","items":{"$ref":"#/components/schemas/TerraUser"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"503":{"$ref":"#/components/responses/AuthorizationUnavailable"}}}}}}
```

## Get info for multiple users

> Returns the users for a list of user IDs, sent as a JSON array in the body.

```json
{"openapi":"3.2.0","info":{"title":"Terra API","version":"2026.11.19"},"tags":[{"name":"User","summary":"User","description":"Look up connected users by user ID or your own reference ID."}],"servers":[{"url":"https://access.tryterra.co/api/v2"}],"security":[{"ApiKeyAuth":[],"DevID":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key for authentication"},"DevID":{"type":"apiKey","in":"header","name":"dev-id","description":"Your developer ID for authentication and tracking"}},"schemas":{"TerraUser":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"user_id":{"type":"string","minLength":1,"description":"Terra identifier for the wearable connection"},"provider":{"type":"string","minLength":1,"description":"Connection data source"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Time at which the connection was created"},"last_webhook_update":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Last time at which a webhook update was sent for the connection"},"scopes":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"(when available) Permissions granted by the user during authentication - to be used as debugging metadata"},"reference_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Connection identifier on the developer's end, used to tie connection back to a user on the developer's platform"},"active":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"whether the user is active or not (inactive users will not receive any data updates and are in considered "}},"required":["user_id","provider"]},"Problem":{"type":"object","description":"An error response, following RFC 9457 (Problem Details for HTTP APIs, which obsoletes RFC 7807). Returned with `Content-Type: application/problem+json` on every 4xx/5xx response. The HTTP status line carries the status code; it is intentionally not repeated in the body. `type`, `title` and `instance` are always present; `detail` is included when a specific explanation is available.\n","properties":{"type":{"type":"string","description":"A URI reference identifying the problem type. Defaults to `about:blank`."},"title":{"type":"string","description":"A short, human-readable summary of the problem type (the lowercased HTTP status text)."},"instance":{"type":"string","description":"The request path, including any query string, that produced this problem."},"code":{"type":"string","description":"Stable error classification: branch on this, not on `detail`. A refused credential returns unauthorized (401: missing, invalid, expired or revoked), scope_missing (403: the credential lacks the scope the operation requires) or audience_restricted (403: the credential is not granted for this dev-id). authorization_unavailable (503) means the credential or the product access could not be checked; retry later. Product gates return entitlement_required (403) or environment_disabled (403). service_unavailable (503) means the request never reached the service; dependency_failed (502 or 504) means the service did not complete it, though it may already have acted on it. Report uploads return validation_failed, unsupported_file_type or too_many_files (400), payload_too_large (413) and rate_limited (429)."},"product":{"type":"string","description":"The product checked by the authorization gate, when classified."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["type","title","instance"]},"UnauthorizedProblem":{"type":"object","description":"A refused credential, always with its code.","properties":{"type":{"type":"string","description":"A URI reference identifying the problem type. Defaults to `about:blank`."},"title":{"type":"string","description":"A short, human-readable summary of the problem type (the lowercased HTTP status text)."},"instance":{"type":"string","description":"The request path, including any query string, that produced this problem."},"code":{"type":"string","description":"Stable error classification: branch on this, not on `detail`. A refused credential returns unauthorized (401: missing, invalid, expired or revoked), scope_missing (403: the credential lacks the scope the operation requires) or audience_restricted (403: the credential is not granted for this dev-id). authorization_unavailable (503) means the credential or the product access could not be checked; retry later. Product gates return entitlement_required (403) or environment_disabled (403). service_unavailable (503) means the request never reached the service; dependency_failed (502 or 504) means the service did not complete it, though it may already have acted on it. Report uploads return validation_failed, unsupported_file_type or too_many_files (400), payload_too_large (413) and rate_limited (429)."},"product":{"type":"string","description":"The product checked by the authorization gate, when classified."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["type","title","instance","code"]}},"responses":{"BadRequest":{"description":"One or more parameters is malformed. The `detail` field describes the specific problem.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"Unauthorized":{"description":"The credential is missing, invalid, expired or revoked (code `unauthorized`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/UnauthorizedProblem"}}}},"NotFound":{"description":"A referenced resource does not exist on Terra's end.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"AuthorizationUnavailable":{"description":"The credential or the product access could not be checked (code `authorization_unavailable`). Retry after the service recovers.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"paths":{"/bulkUserInfo":{"post":{"tags":["User"],"operationId":"User_BatchGet","description":"Returns the users for a list of user IDs, sent as a JSON array in the body.","summary":"Get info for multiple users","requestBody":{"content":{"application/json":{"schema":{"type":"array","description":"List of user IDs to get information for","items":{"type":"string"}}}},"required":true},"responses":{"200":{"description":"Returned upon successful request","content":{"application/json":{"schema":{"type":"object","required":["status","users"],"properties":{"status":{"type":"string","enum":["success"],"default":"success"},"users":{"type":"array","description":"One entry per user ID that matches a user in your environment; IDs that match none are left out rather than refused.","items":{"type":"object","required":["user","is_authenticated"],"properties":{"user":{"allOf":[{"$ref":"#/components/schemas/TerraUser"},{"type":"object","properties":{"provider_user_id":{"type":"string","description":"The user's ID at the provider; empty when Terra does not hold one."}}}]},"is_authenticated":{"type":"boolean","description":"Always `true`."}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"503":{"$ref":"#/components/responses/AuthorizationUnavailable"}}}}}}
```
