---
title: entities.entityHealth
description: Read entity health records with the entityHealth repository, and change them with the entity health mutations. Same records as the REST EntityHealths entity.
canonical: https://developers.coevera.com/reference/graphql/entity-health/
section: graphql
verification: schema
generatedFrom: schema f155746 (2026-10-20)
publisher: Coevera
---

# entities.entityHealth

Read entity health records with the entityHealth repository, and change them with the entity health mutations. Same records as the REST EntityHealths entity.

REST: [EntityHealths](https://developers.coevera.com/reference/rest/entity-healths.md).

## Queries

- `getById(entityId: ID!): EntityHealthEntity` Returns the record with the given id, or null when there is none. Deleted records are returned as well.
- `getByIds(entityIds: [ID!]!): [EntityHealthEntity!]!` Returns the records with the given ids; ids without a record are left out. Deleted records are returned as well.
- `getAll(limit: Int, offset: Int, filter: EntityHealthFilterInput, orderBy: [EntityHealthOrderByInput!], includeDeleted: Boolean): [EntityHealthEntity!]!` Returns the records that match the filter, paged with limit and offset.
- `getByCriteria(filter: EntityHealthFilterInput, orderBy: [EntityHealthOrderByInput!], includeDeleted: Boolean, before: String, after: String, first: Int, last: Int): EntityHealthEntityConnection` Returns the records that match the filter as a cursor-paginated connection.
- `getChangedFieldsSinceRevision(id: UUID!, revision: Int!): [UUID!]!` Returns the ids of the fields of a record that changed after the given revision. Returns an empty list for entities without change tracking.
- `getByTypeId(typeId: UUID!, strict: Boolean): EntityHealthEntity!` Returns the account health configuration for the given account type.

## Mutations

- `updateEntityHealth(input: UpdateEntityHealthInput!, validationLevel: [ValidationLevel!], sessionIdToUpdate: String): UpdateEntityHealthPayload` Update fields.

## Types

### EntityHealthEntity (object)

Health configuration of an account type, defining when accounts of that type are healthy or in critical health.

- `isDeleteProtected: Boolean!` True when the record is protected against deletion because it must always exist in the space. Deleting a record that is not protected can still fail on other checks. Read-only.
- `id: ID!` Unique identifier of entity.
- `isDeleted: Boolean` Specifies if the entity is considered deleted.
- `modified: DateTime` Last modification time.
- `created: DateTime` Creation time.
- `type: AccountTypeEntity` Account type this health configuration applies to.
- `entityType: BaseEntityTypeEnum!` Entity whose records the health configuration evaluates; currently always Account. Read-only.
- `isEnabled: Boolean!` When false, health is configured but not evaluated for records of this type.
- `lastRecalculation: DateTime` Timestamp of the last full health recalculation across all matching records.
- `typeId: ID!` Id of the account type.
- `revision: Int` Revision when entity was lastly changed.
- `settings: EntityHealthSettings!` Health configuration: indicator filter definitions for healthy and critical-health states. Stored as a versioned JSON document; updates create a new history entry.
- `calculationProgress: Int` Progress of the in-flight health recalculation as a percentage (0-100). Null when no recalculation has been queued.
- `instancePermissions: [EntityPermsEnum!]! (1 args)` Permissions the current user has on this record, out of the requested ones.

### EntityHealthEntityConnection (object)

Paginated list of EntityHealth records.

- `pageInfo: PageInfo!` Pagination data for this connection.
- `edges: [EntityHealthEntityEdge]!` Contains the nodes in this connection.
- `totalCount: Int` Total number of items in the connection.

### EntityHealthEntityEdge (object)

A Relay edge containing a `EntityHealthEntity` and its cursor.

- `node: EntityHealthEntity` The item at the end of the edge
- `cursor: String!` A cursor for use in pagination

### EntityHealthFilterInput (input)

Filter conditions for EntityHealth records. Conditions on different fields are combined with AND; use OR, AND and NOT for other combinations.

- `OR: [EntityHealthFilterInput!]` Matches records that meet at least one of the listed filters.
- `AND: [EntityHealthFilterInput!]` Matches records that meet all of the listed filters.
- `NOT: EntityHealthFilterInput` Matches records that do not meet this filter.
- `globalSearchQuery: String` Search term matched against the fields that the global search covers for this entity.
- `id: EntityFilterStringField` Unique identifier of entity.
- `isDeleted: Boolean` Specifies if the entity is considered deleted.
- `modified: EntityFilterDateTimeField` Last modification time.
- `created: EntityFilterDateTimeField` Creation time.
- `entityType: BaseEntityTypeEnumFilterInput` Entity whose records the health configuration evaluates; currently always Account. Read-only.
- `isEnabled: Boolean` When false, health is configured but not evaluated for records of this type.
- `lastRecalculation: EntityFilterDateTimeField` Timestamp of the last full health recalculation across all matching records.
- `typeId: EntityFilterStringField` Id of the account type.
- `revision: EntityFilterNumberField` Revision when entity was lastly changed.
- `type: AccountTypeFilterInput` Account type this health configuration applies to. Matches records where a related record meets these conditions.

### EntityHealthOrderByInput (input)

Sorting of EntityHealth records. Set exactly one field in each item; list several items to sort by more fields, in order of priority.

- `id: OrderByEnum` Unique identifier of entity.
- `isDeleted: OrderByEnum` Specifies if the entity is considered deleted.
- `modified: OrderByEnum` Last modification time.
- `created: OrderByEnum` Creation time.
- `type: [AccountTypeOrderByNestedInput!]` Account type this health configuration applies to. Sorts by fields of the related record, listed in order of priority.
- `isEnabled: OrderByEnum` When false, health is configured but not evaluated for records of this type.
- `lastRecalculation: OrderByEnum` Timestamp of the last full health recalculation across all matching records.
- `typeId: OrderByEnum` Id of the account type.
- `revision: OrderByEnum` Revision when entity was lastly changed.

### UpdateEntityHealthInput (input)

Id of an EntityHealth record and the field values to change.

- `clientMutationId: String` Optional client-supplied identifier passed on a mutation input and echoed back unchanged on its payload, so a client can correlate the response with its request (Relay convention).
- `id: ID!` Unique identifier of entity.
- `modified: DateTime` Last modification time.
- `created: DateTime` Creation time.
- `isEnabled: Boolean` When false, health is configured but not evaluated for records of this type.
- `lastRecalculation: DateTime` Timestamp of the last full health recalculation across all matching records.
- `typeId: ID` Id of the account type.
- `revision: Int` Revision when entity was lastly changed.
- `settings: EntityHealthSettingsJSONString` Health configuration: indicator filter definitions for healthy and critical-health states. Stored as a versioned JSON document; updates create a new history entry.

### UpdateEntityHealthPayload (object)

Result of the updateEntityHealth mutation.

- `entityHealth: EntityHealthEntity` The updated record.
- `clientMutationId: String` Optional client-supplied identifier passed on a mutation input and echoed back unchanged on its payload, so a client can correlate the response with its request (Relay convention).

### EntityHealthCalculationTypeEnum (enum)

How the scores of health indicators are combined into a record's health score.

- `Manual` Each indicator uses the score configured on it.
- `Priority` Scores are derived from the order of the indicators; earlier indicators weigh more.

### EntityHealthFieldConfiguration (object)

Set of health indicator rules: rules on the record itself and rules on its related records.

- `filterMainBox: EntityHealthMainFilterBox!` Indicator rules evaluated directly on the scored entity.
- `filterSiblingBoxes: [EntityHealthFilterBox!]!` Additional rule boxes evaluated on related records, each tied to a relation from the scored entity.

### EntityHealthFilterBox (object)

Group of health indicator rules evaluated on a record related to the scored record.

- `id: String!` Unique identifier of the filter box.
- `entity: String!` Related entity type the indicator rules in this box are evaluated on.
- `lookupFieldId: UUID` Lookup field that connects the scored entity to the related record this box evaluates.
- `relation: HardCodedRelation` Predefined relationship to the related record this box evaluates, such as the next scheduled or last finished activity.
- `filterFields: [EntityHealthFieldFilterRule!]!` Health indicator rules evaluated on the related record.

### EntityHealthMainFilterBox (object)

Group of health indicator rules evaluated on the scored record itself.

- `id: String!` Unique identifier of the filter box.
- `entity: String!` Entity type the indicator rules in this box are evaluated on.
- `lookupFieldId: UUID` When the box evaluates a related record, the lookup field that connects this entity to that record.
- `filterFields: [EntityHealthFieldFilterRule!]!` Health indicator rules evaluated directly on the scored entity.

### EntityHealthSettings (object)

Configuration of a health score: categories, how the score is calculated and the indicator rules.

- `categories: [HealthCategory!]!` Health categories that group records by score range (for example Good, Watch, Critical).
- `calculationType: EntityHealthCalculationTypeEnum!` How indicator scores are combined. Manual uses the score configured on each indicator; Priority derives scores from the order of the indicators.
- `healthIndicators: EntityHealthFieldConfiguration!` Indicator rules that contribute positive or negative points to the health score.
- `criticalHealthIndicators: EntityHealthFieldConfiguration!` Indicator rules that force the record into the critical category when they match.

### FilterBoxInterface (interface)

Group of filter conditions evaluated on one record type.

- `id: String!` Identifier of this filter box within the filter tab.
- `entity: String!` Name of the record type whose fields the conditions in this box are evaluated against.
- `lookupFieldId: UUID` Identifier of the lookup field that connects this box to the main record type when the box filters a related record reached through a lookup.

### HardCodedRelation (object)

Predefined relation that links a filter box to the filtered records.

- `kind: SiblingRelationType!` Predefined relationship that links this filter box to the main record type (for example Primary, Aggregation, NextScheduledActivity).

### HealthCategory (object)

Health category, such as Good or Critical: a score range with its label and color.

- `id: UUID!` Unique identifier of the health category.
- `label: String!` Display name of the health category (for example Good, Watch, Critical).
- `useLang: Boolean!` When true, the label is treated as a translation key and localized in the UI; otherwise the literal label text is shown.
- `value: Int!` Upper health-score threshold of this category. A record falls into the category whose threshold its score does not exceed. The critical category uses -1.
- `color: Int!` Color used to render this category in the UI, encoded as an integer.

### SiblingRelationType (enum)

Predefined relationship that selects which related records of another type a report box or filter box uses for each main record.

- `NoRelation` No predefined relationship is set.
- `Custom` Reserved for a user-defined relationship; not supported.
- `Aggregation` Values of all related records are combined into one value per main record.
- `LastFinishedActivity` The related activity that was finished most recently.
- `NextScheduledActivity` The next upcoming related activity.
- `Primary` The primary related record, such as the primary account or contact; for quotes of an opportunity, the active quote.
- `NextOpenOpportunity` Reserved for the next open opportunity; not supported.
- `LastWonOpportunity` Reserved for the most recently won opportunity; not supported.
- `LastLostOpportunity` Reserved for the most recently lost opportunity; not supported.
- `LastOnlineFormResponse` The most recently created related online form response.
- `LastNote` The most recently created related note.
- `LastMessage` The most recent related message.
- `LastActivityComment` The most recent comment on the activity.
- `All` Every related record; the main record appears once per related record.
- `Sender` The account, contact or user who sent the email.

Types several repositories share, such as `PageInfo` and the filter fields, are in the [types index](https://developers.coevera.com/reference/graphql/types.md). The [SDL](https://developers.coevera.com/graphql/schema.graphql) has the whole schema in one file.

## Example

```graphql
query FirstEntityHealths {
  entities {
    entityHealth {
      getByCriteria(first: 3, orderBy: [{ modified: Desc }]) {
        totalCount
        edges { node { id modified } }
      }
    }
  }
}
```

```bash
curl 'https://{region}.api.coevera.com/api/v100/app/space/{space_id}/graphql/public' \
  --user "$COEVERA_API_KEY:$COEVERA_API_SECRET" \
  --header 'Content-Type: application/json' \
  --data '{"query":"query FirstEntityHealths { entities { entityHealth { getByCriteria(first: 3, orderBy: [{ modified: Desc }]) { totalCount edges { node { id modified } } } } } }"}'
```