> 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/admin-api/environment-doctor-1.md).

# Environment doctor

Check an environment for problems that stop data reaching you.

## Check the environment

> Runs the environment's checks on request and returns one lint per problem, errors first.\
> \
> \- There is no overall status: decide which levels (\`error\`, \`warn\`, \`info\`) fail you.\
> \- Each area's checks run only when the token holds the scope that area's reads need (\`tokens:read\`, \`tokens:admin\`, \`billing:read\`, \`team:read\`, \`providers:read\`, \`connections:read\`, \`events:read\`, \`dataconfig:read\`, \`vantage:read\`, \`vantageconfig:read\`, \`lab\_reports:read\`, \`models:read\`, \`workouts:read\`, \`account:read\`); product checks run only when the environment has the product, and are skipped otherwise.\
> \- Checks that cannot run, for want of a scope or a readable dependency, come back as one \`check\_unavailable\` lint per cause listing them in \`metadata.checks\`, never as a pass.\
> \- \`cache\_key\` stays the same for the same problem across runs; \`remediation.docs\_url\` links to the check in the environment doctor docs.

```json
{"openapi":"3.2.0","info":{"title":"Terra Admin API","version":"2026.11.19"},"tags":[{"name":"doctor","summary":"Environment doctor","description":"Check an environment for problems that stop data reaching you."}],"servers":[{"url":"https://access.tryterra.co/api/v3/admin"}],"security":[{"adminToken":["destinations:read"]}],"components":{"securitySchemes":{"adminToken":{"type":"oauth2","description":"An admin access token (`terra_at_*`), scoped to one customer. Get one with the RFC 8628 device flow (`POST /auth/device`, approve in the dashboard, poll `POST /auth/token`), the authorization-code grant (`GET /auth/authorize`, consent in the dashboard, S256 exchange at `POST /auth/token`), or from the dashboard.\n\n- This API accepts only admin tokens. Data tokens (`terra_dt_*`, minted at `POST /environments/{dev_id}/tokens`) authenticate only the APIs your product calls at runtime, under `/api/v2` and `/api/v3`.\n- Each operation names the scope it needs. An admin token may also be limited to some environments.\n- The scopes below cover both planes. `POST /auth/device` grants only admin-plane scopes and refuses the rest with 400 `invalid_scope`; `x-scope-planes` says which plane each scope belongs to, and a data-plane scope's description starts with `Data plane:`.\n- `x-scope-dangerous` (off by default, mapped to what each puts at stake), `x-scope-sensitive` (on by default, labelled), `x-scope-account-level` (not available to an environment-limited token) and `x-scope-presets` (the approval page's grant sets) classify the admin scopes. Each scope's description is the sentence the approval page shows.\n- The `deviceAuthorization` flow is the device grant and the `authorizationCode` flow the browser grant; both take the same scopes. There is no client-credentials grant: the `clientCredentials` flow only carries the scopes and the `x-scope-*` lists, where existing clients read them.","flows":{"clientCredentials":{"tokenUrl":"/api/v3/admin/auth/token","scopes":{"account:read":"See your account details and environment IDs.","keys:read":"See your API key, the secret values of your data access tokens and the credentials your destinations use.","keys:write":"Replace your API key. Anything using the old key will stop working.","providers:read":"See which wearables and apps are turned on, and their settings.","providers:write":"Turn wearables and apps on or off, and change their sign-in settings.","destinations:read":"See where your data is sent, like a webhook or Supabase.","destinations:write":"Add, change or remove where your data is sent.","events:read":"See a log of the data sent to you, without its contents.","events:write":"Send data again.","connections:read":"See which of your users have connected.","payloads:read":"See your users' health data, both what was sent to you and what is stored for them.","dataconfig:read":"See which health data fields you get.","dataconfig:write":"Change which health data fields you get.","vantageconfig:read":"See which Vantage products and markets are turned on, and the products you can turn on.","vantageconfig:write":"Turn Vantage products and markets on or off, and change the Vantage API version.","scores:read":"See which scores are turned on, and their settings.","scores:write":"Turn scores on and change their settings.","models:read":"See the available models and their past results.","models:run":"Data plane: run a model over a user's stored data.","workouts:read":"Data plane: read workout templates and planned workouts.","workouts:write":"Data plane: create workout templates and plan workouts for users.","labreports:read":"Data plane: read lab reports.","labreports:write":"Data plane: reprocess or delete lab reports.","testdata:write":"Send made-up health data to where your data goes, from one-off events or test users you can start and stop.","billing:read":"See your plan, invoices, payment method and usage.","billing:write":"Change your plan, pay invoices and update payment details. This can spend money.","tokens:admin":"See and revoke every token across your account, including other people's.","entitlements:read":"See which features your company has access to.","auth:write":"Data plane: create user authentication flows — widget sessions, auth tokens (in place of a client_secret).","connections:write":"Data plane: deauthenticate users and update connection attributes.","data:read":"Data plane: read stored end-user health data (activity, sleep, body, …).","data:write":"Data plane: push or delete end-user health data.","routes:read":"Data plane: read routes and pushed routes.","routes:write":"Data plane: create, update, push, and delete routes.","datalinks:read":"Data plane: read data links.","datalinks:write":"Data plane: create and delete data links.","graphs:read":"Data plane: read graph sessions.","graphs:write":"Data plane: create and manage graph sessions (public renders of health data).","vantage:read":"See your Vantage orders and results, including who they are for.","vantage:write":"Data plane: create Vantage orders, simulate orders and update configuration or result acknowledgments. Includes vantage:read.","agents:read":"Data plane: read agents, bundles, jobs, and schedules.","agents:write":"Data plane: create, update, and delete agents and their configuration.","agents:run":"Data plane: execute agents and bundles (incurs model spend).","ai:run":"Data plane: run AI-context queries and the MCP proxy.","tokens:read":"See the data access tokens in an environment, but not their secret values.","tokens:write":"Create and revoke data access tokens in an environment, including other people's. A new token can do anything it's given access to.","account:write":"Change your profile and your company's details.","team:read":"See who is on your team.","team:write":"Invite, change or remove team members. This can take away someone's access."}},"authorizationCode":{"authorizationUrl":"/api/v3/admin/auth/authorize","tokenUrl":"/api/v3/admin/auth/token","scopes":{"account:read":"See your account details and environment IDs.","keys:read":"See your API key, the secret values of your data access tokens and the credentials your destinations use.","keys:write":"Replace your API key. Anything using the old key will stop working.","providers:read":"See which wearables and apps are turned on, and their settings.","providers:write":"Turn wearables and apps on or off, and change their sign-in settings.","destinations:read":"See where your data is sent, like a webhook or Supabase.","destinations:write":"Add, change or remove where your data is sent.","events:read":"See a log of the data sent to you, without its contents.","events:write":"Send data again.","connections:read":"See which of your users have connected.","payloads:read":"See your users' health data, both what was sent to you and what is stored for them.","dataconfig:read":"See which health data fields you get.","dataconfig:write":"Change which health data fields you get.","vantageconfig:read":"See which Vantage products and markets are turned on, and the products you can turn on.","vantageconfig:write":"Turn Vantage products and markets on or off, and change the Vantage API version.","scores:read":"See which scores are turned on, and their settings.","scores:write":"Turn scores on and change their settings.","models:read":"See the available models and their past results.","models:run":"Data plane: run a model over a user's stored data.","workouts:read":"Data plane: read workout templates and planned workouts.","workouts:write":"Data plane: create workout templates and plan workouts for users.","labreports:read":"Data plane: read lab reports.","labreports:write":"Data plane: reprocess or delete lab reports.","testdata:write":"Send made-up health data to where your data goes, from one-off events or test users you can start and stop.","billing:read":"See your plan, invoices, payment method and usage.","billing:write":"Change your plan, pay invoices and update payment details. This can spend money.","tokens:admin":"See and revoke every token across your account, including other people's.","entitlements:read":"See which features your company has access to.","auth:write":"Data plane: create user authentication flows — widget sessions, auth tokens (in place of a client_secret).","connections:write":"Data plane: deauthenticate users and update connection attributes.","data:read":"Data plane: read stored end-user health data (activity, sleep, body, …).","data:write":"Data plane: push or delete end-user health data.","routes:read":"Data plane: read routes and pushed routes.","routes:write":"Data plane: create, update, push, and delete routes.","datalinks:read":"Data plane: read data links.","datalinks:write":"Data plane: create and delete data links.","graphs:read":"Data plane: read graph sessions.","graphs:write":"Data plane: create and manage graph sessions (public renders of health data).","vantage:read":"See your Vantage orders and results, including who they are for.","vantage:write":"Data plane: create Vantage orders, simulate orders and update configuration or result acknowledgments. Includes vantage:read.","agents:read":"Data plane: read agents, bundles, jobs, and schedules.","agents:write":"Data plane: create, update, and delete agents and their configuration.","agents:run":"Data plane: execute agents and bundles (incurs model spend).","ai:run":"Data plane: run AI-context queries and the MCP proxy.","tokens:read":"See the data access tokens in an environment, but not their secret values.","tokens:write":"Create and revoke data access tokens in an environment, including other people's. A new token can do anything it's given access to.","account:write":"Change your profile and your company's details.","team:read":"See who is on your team.","team:write":"Invite, change or remove team members. This can take away someone's access."}},"deviceAuthorization":{"deviceAuthorizationUrl":"/api/v3/admin/auth/device","tokenUrl":"/api/v3/admin/auth/token","scopes":{"account:read":"See your account details and environment IDs.","keys:read":"See your API key, the secret values of your data access tokens and the credentials your destinations use.","keys:write":"Replace your API key. Anything using the old key will stop working.","providers:read":"See which wearables and apps are turned on, and their settings.","providers:write":"Turn wearables and apps on or off, and change their sign-in settings.","destinations:read":"See where your data is sent, like a webhook or Supabase.","destinations:write":"Add, change or remove where your data is sent.","events:read":"See a log of the data sent to you, without its contents.","events:write":"Send data again.","connections:read":"See which of your users have connected.","payloads:read":"See your users' health data, both what was sent to you and what is stored for them.","dataconfig:read":"See which health data fields you get.","dataconfig:write":"Change which health data fields you get.","vantageconfig:read":"See which Vantage products and markets are turned on, and the products you can turn on.","vantageconfig:write":"Turn Vantage products and markets on or off, and change the Vantage API version.","scores:read":"See which scores are turned on, and their settings.","scores:write":"Turn scores on and change their settings.","models:read":"See the available models and their past results.","models:run":"Data plane: run a model over a user's stored data.","workouts:read":"Data plane: read workout templates and planned workouts.","workouts:write":"Data plane: create workout templates and plan workouts for users.","labreports:read":"Data plane: read lab reports.","labreports:write":"Data plane: reprocess or delete lab reports.","testdata:write":"Send made-up health data to where your data goes, from one-off events or test users you can start and stop.","billing:read":"See your plan, invoices, payment method and usage.","billing:write":"Change your plan, pay invoices and update payment details. This can spend money.","tokens:admin":"See and revoke every token across your account, including other people's.","entitlements:read":"See which features your company has access to.","auth:write":"Data plane: create user authentication flows — widget sessions, auth tokens (in place of a client_secret).","connections:write":"Data plane: deauthenticate users and update connection attributes.","data:read":"Data plane: read stored end-user health data (activity, sleep, body, …).","data:write":"Data plane: push or delete end-user health data.","routes:read":"Data plane: read routes and pushed routes.","routes:write":"Data plane: create, update, push, and delete routes.","datalinks:read":"Data plane: read data links.","datalinks:write":"Data plane: create and delete data links.","graphs:read":"Data plane: read graph sessions.","graphs:write":"Data plane: create and manage graph sessions (public renders of health data).","vantage:read":"See your Vantage orders and results, including who they are for.","vantage:write":"Data plane: create Vantage orders, simulate orders and update configuration or result acknowledgments. Includes vantage:read.","agents:read":"Data plane: read agents, bundles, jobs, and schedules.","agents:write":"Data plane: create, update, and delete agents and their configuration.","agents:run":"Data plane: execute agents and bundles (incurs model spend).","ai:run":"Data plane: run AI-context queries and the MCP proxy.","tokens:read":"See the data access tokens in an environment, but not their secret values.","tokens:write":"Create and revoke data access tokens in an environment, including other people's. A new token can do anything it's given access to.","account:write":"Change your profile and your company's details.","team:read":"See who is on your team.","team:write":"Invite, change or remove team members. This can take away someone's access."}}}}},"parameters":{"DevId":{"name":"dev_id","in":"path","required":true,"schema":{"type":"string"},"description":"The developer-id (the only tenant-targeting input)."}},"schemas":{"DoctorReport":{"type":"object","description":"The environment's lints, worked out when asked.","properties":{"lints":{"type":"array","description":"Problems found, errors first. Checks that could not run are check_unavailable lints, one per cause, never a pass. Empty when there are none.","items":{"$ref":"#/components/schemas/DoctorLint"}}},"required":["lints"]},"DoctorLint":{"type":"object","description":"One problem with the environment, or a check that could not run.","properties":{"name":{"type":"string","description":"The check that found it, or check_unavailable."},"title":{"type":"string"},"level":{"type":"string","enum":["error","warn","info"],"description":"error stops data reaching you or breaks your integration; warn needs attention; info is worth knowing."},"facing":{"type":"string","enum":["external"],"description":"Always external: every lint concerns your use of Terra."},"categories":{"type":"array","description":"security, performance or health.","items":{"type":"string","enum":["security","performance","health"]}},"description":{"type":"string","description":"What the check looks for, the same for every lint it makes."},"detail":{"type":"string","description":"This lint in particular."},"remediation":{"$ref":"#/components/schemas/DoctorRemediation"},"metadata":{"$ref":"#/components/schemas/DoctorLintMetadata"},"cache_key":{"type":"string","description":"Stable for the same problem across runs: the check, plus the id of what it concerns when there is one."},"observed_at":{"type":"string","format":"date-time","description":"When the check ran."}},"required":["name","title","level","facing","categories","description","detail","remediation","metadata","cache_key","observed_at"]},"DoctorRemediation":{"type":"object","description":"How to act on a lint.","properties":{"text":{"type":"string","description":"What to do, in a sentence."},"action":{"type":["string","null"],"description":"The operationId of the admin call that inspects or fixes the problem, or null."},"docs_url":{"type":["string","null"],"description":"The check's section in the environment doctor docs."}},"required":["text","action","docs_url"]},"DoctorLintMetadata":{"type":"object","description":"What a lint concerns, and the facts behind it.","properties":{"type":{"type":"string","description":"destination, source, token, subscription, meter, invitation, data_type, api_version, model, route, environment, account (the problem is account-wide and shows in every environment), or check for a check_unavailable lint."},"id":{"type":["string","null"],"description":"The id of what the lint concerns, string-encoded. Null for the environment as a whole, and for a check_unavailable lint."},"name":{"type":["string","null"],"description":"A display name for it, or null."},"reason":{"type":["string","null"],"description":"A stable reason code: a delivery error code, a disabled reason, a subscription or certificate state, or why checks could not run (missing_scope, dependency_unavailable). Null when there is none."},"scope":{"type":["string","null"],"description":"The admin scope the token needs, when a check could not run for want of it."},"since":{"type":["string","null"],"format":"date-time","description":"When the problem began or comes due, when Terra knows."},"observed":{"description":"The counts behind the lint, keyed by name. omitted, on the last lint a check returns, counts the lints left out once a check reaches 25.","$ref":"#/components/schemas/RecordInteger"},"checks":{"type":["array","null"],"description":"The checks a check_unavailable lint covers. Null for every other lint.","items":{"type":"string"}}},"required":["type","id","name","reason","scope","since","observed","checks"],"$defs":{"RecordInteger":{"type":"object","unevaluatedProperties":{"type":"integer"}}}},"RecordInteger":{"type":"object","unevaluatedProperties":{"type":"integer"}},"AdminProblem":{"allOf":[{"$ref":"#/components/schemas/Problem"},{"$ref":"#/components/schemas/ProblemExtensions"}]},"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"]},"ProblemExtensions":{"type":"object","description":"The admin surface's additions to the shared RFC 9457 Problem in specs/components/common.yaml, which contributes type/title/instance/detail. Composed with it via allOf in apis/admin.yaml rather than restated, so the two cannot drift. No `status`: httptools.Problem.MarshalJSON never writes it — the response line is authoritative.","properties":{"code":{"type":"string","enum":["access_denied","api_key_not_found","audience_restricted","authorization_pending","authorization_unavailable","billing_unavailable","conflict","dependency_failed","dev_id_not_found","device_code_expired","endpoint_moved","entitlement_required","environment_disabled","idempotency_key_reuse","internal_error","not_claimable","not_found","not_ready","precondition_failed","provider_credentials_rejected","rate_limited","rotation_conflict","rotation_expired","scope_missing","service_unavailable","slow_down","token_expired","token_limit_reached","token_not_found","unauthorized","unsupported_operation","validation_failed"],"description":"Stable error code — branch on this, not on prose."},"remediation":{"type":"string","description":"How an agent can recover."},"errors":{"type":"array","description":"Field-level validation errors (\"field: message\").","items":{"type":"string"}}},"required":["code"]}},"responses":{"ValidationError":{"description":"Request validation failed (see errors[]).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}},"Unauthorized":{"description":"Missing/invalid/expired admin token.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}},"Forbidden":{"description":"The token is missing the required scope.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}},"NotFound":{"description":"Resource not found (or not owned — no existence oracle).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}},"RateLimited":{"description":"Per-token rate limit exceeded; see Retry-After.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/AdminProblem"}}}}}},"paths":{"/environments/{dev_id}/doctor":{"get":{"operationId":"getDoctor","tags":["doctor"],"summary":"Check the environment","description":"Runs the environment's checks on request and returns one lint per problem, errors first.\n\n- There is no overall status: decide which levels (`error`, `warn`, `info`) fail you.\n- Each area's checks run only when the token holds the scope that area's reads need (`tokens:read`, `tokens:admin`, `billing:read`, `team:read`, `providers:read`, `connections:read`, `events:read`, `dataconfig:read`, `vantage:read`, `vantageconfig:read`, `lab_reports:read`, `models:read`, `workouts:read`, `account:read`); product checks run only when the environment has the product, and are skipped otherwise.\n- Checks that cannot run, for want of a scope or a readable dependency, come back as one `check_unavailable` lint per cause listing them in `metadata.checks`, never as a pass.\n- `cache_key` stays the same for the same problem across runs; `remediation.docs_url` links to the check in the environment doctor docs.","parameters":[{"$ref":"#/components/parameters/DevId"},{"name":"name","in":"query","required":false,"description":"Run only these checks, by lint name. Comma-separate them or repeat the parameter; a check matching any of them runs. An unknown name is a 400. Combines with category to choose which lints come back.","style":"form","explode":false,"schema":{"type":"array","items":{"type":"string"}}},{"name":"category","in":"query","required":false,"description":"Run only the checks in these categories. Comma-separate them or repeat the parameter. A check in any of them runs. Combines with name to choose which lints come back.","style":"form","explode":false,"schema":{"type":"array","items":{"type":"string","enum":["security","performance","health"]}}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DoctorReport"}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}}}}
```
