---
sourceDocument: Xanadu API Reference
sourceDocumentLink: https://servicenow-prod.fluidtopics.net/r/xanadu/api-reference

 Release :

    - xanadu

ft:locale :

    - en-US

ft:publication_title :

    - Xanadu API Reference

ft:clusterId :

    - crapiref

bundleId :

    - crapiref

workflow :

    - Creator


---

# ActivitySubscriptions API

# ActivitySubscriptions API {#ariaid-title1}

* Release version: Xanadu
* 
* Updated August 1, 2024
* 
* ![](https://www.servicenow.com/docs/portal-asset/ico-clock) 21 minutes to read

The ActivitySubscriptions API provides endpoints to retrieve Activity
entities from the Subscriptions and Activity Feed Framework.
This API requires activation of the Subscriptions and Activity Feed Framework
(com.snc.activity_subscriptions) plugin. Activate the Customer Central
(com.sn_csm_customer_central) plugin to seed configuration in all required tables. For more
information on customer central configuration settings, see [Configure customer central](https://www.servicenow.com/docs/access?context=configure-customer-central&version=xanadu&pubname=xanadu-customer-service-management&ft:locale=en-US).

## Aggregate API {#ariaid-title2}

The Aggregate API provides endpoints that allow you to compute
aggregate statistics about existing table and column data.

For Aggregate API requests, you must have
read access for all records in the table you query. If an ACL prevents the requesting user
from accessing any record in the table, the request returns a 403 Forbidden error.

### Aggregate - GET /now/stats/{tableName} {#ariaid-title3}

Retrieves records for the specified table and performs aggregate functions on the
returned values.
You can specify which aggregate functions to perform by using either the
sysparm_\<aggregate\>_fields parameter or
sysparm_having=\<aggregate\>\^field\^operator\^value parameter,
substituting \<aggregate\> for one of these aggregate
functions:  
* avg
* max
* min
* sum
{#aggregate-GET-stats__ul_yyv_vcn_yq}

#### URL format {#aggregate-GET-stats__section_qsm_m1r_cmb}

Versioned URL:
/api/now/{api_version}/stats/{tableName}

Default URL:
/api/now/stats/{tableName}

#### Supported request parameters

{#aggregate-GET-stats__entry__2}{#aggregate-GET-stats__version-not_optional-RESTAPI}

| Name | Description |
|-|-|
| api_version | Optional. Version of the endpoint to access. For example, <kbd class="ph userinput">v1</kbd> or <kbd class="ph userinput">v2</kbd>. Only specify this value to use an endpoint version other than the latest. Data type: String |
| tableName | Name of the table for which to retrieve records. Data type: String |
[Table 1. Path parameters]

{#aggregate-GET-stats__entry__8}

| Name | Description |
|-|-|
| name-value pairs | An alternative to using the sysparm_query parameter. You can filter a query using key-value pairs where the key is the name of a field. For example, instead of using the parameter `&sysparm_query=active=true`, you can use `&active=true`. You can use the display value when the field is a choice or reference type field, such as `&state=closed` instead of `&state=7`. To specify multiple key-value pairs, separate each with an ampersand, such as `&active=true&assigned_to=john.smith`. Data type: String |
| sysparm_\<aggregate\>_fields | List of fields on which to perform each aggregate operation. You can specify multiple fields by separating each with a comma. For example, to get the average values from the duration and priority fields, use `sysparm_avg_fields=duration,priority`. Note: Specify this parameter, the sysparm_count parameter, or both for your query to return meaningful results. If neither parameter is passed, no aggregate operation is performed. Data type: String |
| sysparm_count | Flag that determines whether to return the number of records returned by the query. Note: Specify this parameter, the sysparm_\<aggregate\>_fields parameter, or both for your query to return meaningful results. If neither parameter is passed, no aggregate operation is performed. Data type: String |
| sysparm_display_value | Data retrieval operation when grouping by reference or choice fields. Based on this value, the query returns either the display value, the actual value in the database, or both. * true: Returns display values for all fields. * false: Returns actual values from the database. If a value is not specified, this parameter defaults to false. * all: Returns both actual and display values. {#aggregate-GET-stats__ul_eyx_ccn_yq}There is no preferred method for setting this parameter. However, specifying the display value may cause performance issues as they are not read from the database and may reference other fields and records. For more information on display values and actual values, see [Table API FAQs (KB0534905)](https://support.servicenow.com/kb_view.do?sysparm_article=KB0534905). Data type: String |
| sysparm_group_by | Fields by which to group the returned data. You can specify multiple fields by separating each field with a comma, such as `sysparm_group_by=priority,state`. Data type: String |
| sysparm_having | Additional query that enables you to filter the data based on an aggregate operation. The value for this parameter must follow the syntax `aggregate^field^operator^value`, such as `count^priority^>^3` to obtain the number of records within the query results with a priority greater than 3. You can specify multiple queries by separating each with a comma, such `ascount^state^=^1,avg^priority^>^3`. Data type: String |
| sysparm_order_by | List of values by which to order grouped results. You can specify an order using a field or an aggregate. For example, if you specify `sysparm_order_by=AVG^state`, groups of results with lower average state values are returned first. You can also order by COUNT to arrange groups of records by the number of records in each group. When you specify an order, groups are ordered in ascending order by default. Use `^DESC` to sort in descending order, such as `sysparm_order_by=state^DESC`. Data type: String |
| sysparm_query | An encoded query. For example: `(sysparm_query=active=true)(sysparm_query=caller_id=javascript:gs.getUserID()^active=true)` Data type: String |
[Table 2. Query parameters]

{#aggregate-GET-stats__entry__26}

| Name | Description |
|-|-|
| None |   |
[Table 3. Request body parameters (XML or JSON)]

#### Headers

The following request and response headers apply to this HTTP
action only, or apply to this action in a distinct way. For a list of general headers used
in the REST API, see [Supported REST API headers](https://servicenow-prod.fluidtopics.net/2vuQj3~2s_niNXyXhrbRZA "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other.").
{#aggregate-GET-stats__entry__30}{#aggregate-GET-stats__accept-RESTAPI}

| Header | Description |
|-|-|
| Accept | Data format of the response body. Supported types: application/json or application/xml. Default: application/json |
[Table 4. Request headers]

{#aggregate-GET-stats__entry__34}

| Header | Description |
|-|-|
| None |   |
[Table 5. Response headers]

#### Status codes

The following status codes apply to this HTTP action. For a
list of possible status codes used in the REST API, see [REST API HTTP response
codes](https://servicenow-prod.fluidtopics.net/2vuQj3~2s_niNXyXhrbRZA "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other.").
{#aggregate-GET-stats__entry__38}{#aggregate-GET-stats__entry-200-status-code}{#aggregate-GET-stats__entry-401-status-code}{#aggregate-GET-stats__entry-500-status-code}

| Status code | Description |
|-|-|
| 200 | Successful. The request was successfully processed. |
| 401 | Unauthorized. The user credentials are incorrect or have not been passed. |
| 500 | Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error. |
[Table 6. Status codes]

#### Response body parameters (JSON or XML)

{#aggregate-GET-stats__entry__46}

| Name | Description |
|-|-|
| Depends on specified table and specified request parameters. |   |
[ ]

#### Sample cURL request

    curl "https://instance.servicenow.com/api/now/stats/incident?sysparm_avg_fields=reassignment_count%2Cbusiness_stc&sysparm_group_by=assignment_group" \
    --request GET \
    --header "Accept:application/json" \
    --user "username":"password"

    {
      "result": [
        {
          "stats": {
            "avg": {
              "business_stc": "804162.7143",
              "reassignment_count": "1.0000"
            }
          },
          "groupby_fields": [
            {
              "value": "",
              "field": "assignment_group"
            }
          ]
        },
        {
          "stats": {
            "avg": {
              "business_stc": "2037371.0000",
              "reassignment_count": "1.5000"
            }
          },
          "groupby_fields": [
            {
              "value": "287ee6fea9fe198100ada7950d0b1b73",
              "field": "assignment_group"
            }
          ]
        },
        {
          "stats": {
            "avg": {
              "business_stc": "1821488.2857",
              "reassignment_count": "1.1111"
            }
          },
          "groupby_fields": [
            {
              "value": "8a5055c9c61122780043563ef53438e3",
              "field": "assignment_group"
            }
          ]
        },
        {
          "stats": {
            "avg": {
              "business_stc": "1730322.0000",
              "reassignment_count": "1.2500"
            }
          },
          "groupby_fields": [
            {
              "value": "287ebd7da9fe198100f92cc8d1d2154e",
              "field": "assignment_group"
            }
          ]
        },
        {
          "stats": {
            "avg": {
              "business_stc": "1564478.6250",
              "reassignment_count": "1.2500"
            }
          },
          "groupby_fields": [
            {
              "value": "d625dccec0a8016700a222a0f7900d06",
              "field": "assignment_group"
            }
          ]
        },
        {
          "stats": {
            "avg": {
              "business_stc": "1512202.2500",
              "reassignment_count": "1.1111"
            }
          },
          "groupby_fields": [
            {
              "value": "8a4dde73c6112278017a6a4baf547aa7",
              "field": "assignment_group"
            }
          ]
        }
      ]
    }

## ActivitySubscriptions - GET /now/actsub/activities {#ariaid-title4}

Retrieves activity records from the Subscriptions and Activity Feed
Framework.
No role is required to access this endpoint, but data returned is limited by user access
settings.

### URL format

Versioned URL:
/api/now/{api_version}/actsub/activities

Default URL:
/api/now/actsub/activities

### Supported request parameters

{#actsub-GET-activities__entry__2}{#actsub-GET-activities__version-not_optional-RESTAPI}

| Name | Description |
|-|-|
| api_version | Optional. Version of the endpoint to access. For example, <kbd class="ph userinput">v1</kbd> or <kbd class="ph userinput">v2</kbd>. Only specify this value to use an endpoint version other than the latest. Data type: String |
[Table 7. Path parameters]

{#actsub-GET-activities__entry__6}{#actsub-GET-activities__end-date-query-param-entry}{#actsub-GET-activities__start-date-query-param-entry}

| Name | Description |
|-|-|
| before | Date/time value. The request returns only records created prior to this date and time. Data type: String Format: YYYY-MM-DD hh:mm:ss or YYYY-MM-DD |
| context | Required. Sys_id of an activity context. Located in the Activity Context \[sn_actsub_activity_context\] table. Predefined activity contexts include Consumer and Contact. Data type: String |
| context_instance | Required. Sys_id of an instance of the specified activity context, representing the initiator of the activities you want to retrieve. Located in the appropriate table for the activity context. As an example, if you set context to the sys_id of the Consumer activity context, set this parameter to the sys_id of the Consumer \[csm_consumer\] table record for the consumer whose activities you want to retrieve. Data type: String |
| end_date | Date/time value. The request returns only records created during the time period defined by start_date and this parameter. Must be set along with start_date. Data type: String Format: YYYY-MM-DD hh:mm:ss or YYYY-MM-DD |
| facets | Comma-separated list of sys_ids of activity facet types to retrieve for the specified activity context. These sys_ids are located in the Activity Facet \[sn_actsub_facet\] table. For more details on activity facets, see [Create facets for activity contexts](https://www.servicenow.com/docs/access?context=create-facet-customer-central&version=xanadu&pubname=xanadu-customer-service-management&ft:locale=en-US). Data type: String Default: Return all activity facet types configured for the activity context. |
| last | Index value of the first result row omitted from the response body. The result row index starts at 0, so the last row included in the response body is the one with the index last-1. For example, setting `last=5` omits rows with index 5 and above and returns at most only the first five result rows (with index values 0 through 4). Setting `stFrom=1` and `last=5` skips the first result row and returns the second through fifth result rows (with index values 1 through 4). Data type: Number (integer) Default: The value of the com.snc.actsub.activities.api.fetch.limit system property (10 by default). |
| record_id | Sys_id of a record to use when rendering dynamic facets. Located in the appropriate table for the activity type you want to retrieve. For example, if you want to fetch activities for a Case record, set this parameter to the sys_id of the Case record in question. For more details on dynamic facets, see [Create facets for activity contexts](https://www.servicenow.com/docs/access?context=create-facet-customer-central&version=xanadu&pubname=xanadu-customer-service-management&ft:locale=en-US). Data type: String |
| start_date | Date/time value. The request returns only records created during the time period defined by this parameter and end_date. Must be set along with end_date. Data type: String Format: YYYY-MM-DD hh:mm:ss or YYYY-MM-DD |
| stFrom | Index value of the first result row to include in the response body. The result row index starts at 0. For example, `stFrom=2` skips the first two result rows and returns results from the third row onward. Data type: Number (integer) Default: 0 |
[Table 8. Query parameters]

{#actsub-GET-activities__entry__26}

| Name | Description |
|-|-|
| None |   |
[Table 9. Request body parameters (XML or JSON)]

### Headers

The following request and response headers apply to this HTTP
action only, or apply to this action in a distinct way. For a list of general headers used
in the REST API, see [Supported REST API headers](https://servicenow-prod.fluidtopics.net/2vuQj3~2s_niNXyXhrbRZA "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other.").
{#actsub-GET-activities__entry__30}{#actsub-GET-activities__accept-RESTAPI}

| Header | Description |
|-|-|
| Accept | Data format of the response body. Supported types: application/json or application/xml. Default: application/json |
[Table 10. Request headers]

{#actsub-GET-activities__entry__34}

| Header | Description |
|-|-|
| None |   |
[Table 11. Response headers]

### Status codes

The following status codes apply to this HTTP action. For a
list of possible status codes used in the REST API, see [REST API HTTP response
codes](https://servicenow-prod.fluidtopics.net/2vuQj3~2s_niNXyXhrbRZA "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other.").
{#actsub-GET-activities__entry__38}{#actsub-GET-activities__entry-200-status-code}{#actsub-GET-activities__entry-400-status-code}{#actsub-GET-activities__entry-401-status-code}{#actsub-GET-activities__entry-500-status-code}

| Status code | Description |
|-|-|
| 200 | Successful. The request was successfully processed. |
| 400 | Bad Request. A bad request type or malformed request was detected. The response body result.message parameter describes the nature of the error. Example error messages: * Make sure a valid context and context_instance are passed or Make sure a valid stream and user are passed indicates that the request lacks one or both of the context and context_instance query parameters. These parameters are required. * stFrom can not be greater than last indicates that the stFrom query parameter value exceeds the last query parameter value. * Please provide start_date and end_date indicates that the request includes only one of the start_date and end_date query parameters, which cannot be used separately. * start_date can not be ahead of end_date indicates that the specified start_date query parameter value occurs after the specified end_date query parameter value. * Provided context is not configured in the system indicates that the context query parameter value does not represent a valid activity context. * Make sure a valid context_instance is passed indicates that the context_instance query parameter value does not represent a valid instance of the specified activity context. {#actsub-GET-activities__ul_cvl_5c4_ylb} |
| 401 | Unauthorized. The user credentials are incorrect or have not been passed. |
| 500 | Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error. |
[Table 12. Status codes]

### Response body parameters (JSON or XML)

{#actsub-GET-activities__entry__48}

| Name | Description |
|-|-|
| result | Result object. Data type: Object "result": { "activities": [Array], "message": "String", "status": Number, "stream": "String", "user": "String" } |
| result.activities | Array of objects in which each object represents an activity record from the specified activity context and context instance. Data type: Array of Objects "activities": [ { "activity_type_id": "String", "content_fields": [Array], "created": "String", "icon": "String", "source_table_name": "String", "subheader_fields": [Array], "subobject_sys_id": "String", "subobject_table_name": "String", "sys_id": "String", "title": "String" } ] |
| result.activities.activity_type_id | Sys_id of the record from the Activity Types \[sn_actsub_activity_type\] table that corresponds to the type of this activity record. Data type: String |
| result.activities.content_fields | Array of objects in which each object represents a field to display as content in the tile for the activity record. Data type: Array of Objects "content_fields": [ { "deeplink_to_subobject": "String", "display_as_timeago": "String", "label": "String", "show_label": "String", "type": "String", "value": "String" } ] |
| result.activities.content_fields.deeplink_to_subobject | Flag indicating whether or not the content field displays as a hyperlink to the record for the object on which this activity was performed. Valid values: * true: The content field displays as a hyperlink to the record for the object on which this activity was performed. * false: The content field displays as a hyperlink to the record for the object on which this activity was performed. {#actsub-GET-activities__ul_ej4_bj4_ylb} Data type: String |
| result.activities.content_fields.display_as_timeago | Flag indicating whether or not the content field displays in time ago format. Valid values: * true: The content field displays in time ago format. * false: The content field does not display in time ago format. {#actsub-GET-activities__ul_kj4_bj4_ylb} Data type: String |
| result.activities.content_fields.label | Label for the content field. Data type: String |
| result.activities.content_fields.show_label | Flag indicating whether or not the content field label displays for content field values in the tile for this activity record. Valid values: * true: The content field label displays for content field values in the tile for this activity record. * false: The content field label doesn't display for content field values in the tile for this activity record. {#actsub-GET-activities__ul_sj4_bj4_ylb} Data type: String |
| result.activities.content_fields.type | Type of the content field. Data type: String |
| result.activities.content_fields.value | Value of the content field. Data type: String |
| result.activities.created | Creation date/time for this activity record. Data type: String Format: YYYY-DD-MM hh:mm:ss |
| result.activities.icon | Name of the icon displayed on the tile for this activity record. Data type: String |
| result.activities.source_table_name | Name of the table in which this activity record is located. Determined by the Activity Source defined in the Activity Types \[sn_actsub_activity_type\] table for the type associated with this activity record. Data type: String |
| result.activities.subheader_fields | Array of objects in which each object represents a field displayed in the subheader of the tile for this activity record. Data type: Array of Objects "subheader_fields": [ { "deeplink_to_subobject": "String", "display_as_timeago": "String", "label": "String", "show_label": "String", "type": "String", "value": "String" } ] |
| result.activities.subheader_fields.deeplink_to_subobject | Flag indicating whether or not the subheader field displays as a hyperlink to the record for the object on which this activity was performed. Valid values: * true: The subheader field displays as a hyperlink to the record for the object on which this activity was performed. * false: The subheader field doesn't display as a hyperlink to the record for the object on which this activity was performed. {#actsub-GET-activities__ul_ppz_534_ylb} Data type: String |
| result.activities.subheader_fields.display_as_timeago | Flag indicating whether or not the subheader field displays in time ago format. Valid values: * true: The subheader field displays in time ago format. * false: The subheader field doesn't display in time ago format. {#actsub-GET-activities__ul_oqv_y34_ylb} Data type: String |
| result.activities.subheader_fields.label | Label for the subheader field. Data type: String |
| result.activities.subheader_fields.show_label | Flag indicating whether or not the subheader field label displays for subheader field values in the tile for this activity record. Valid values: * true: The subheader field label displays for subheader field values in the tile for this activity record. * false: The subheader field label doesn't display for subheader field values in the tile for this activity record. {#actsub-GET-activities__ul_iws_q34_ylb} Data type: String |
| result.activities.subheader_fields.type | Type of the subheader field. Data type: String |
| result.activities.subheader_fields.value | Value of the subheader field. Data type: String |
| result.activities.subobject_sys_id | Sys_id of the record for the object on which this activity was performed. Located in the table specified in the subobject_table_name parameter value. Data type: String |
| result.activities.subobject_table_name | Name of the table containing the record for the object on which this activity was performed. Determined by the Table Name defined in the Activity Group \[sn_actsub_subscribable_object\] table for the group containing the activity type associated with this activity record. Data type: String |
| result.activities.sys_id | Sys_id of this activity record. Located in the table specified as the source_table_name response body parameter value. Data type: String |
| result.activities.title | Title that displays on the tile for this activity record. Data type: String |
| result.hasMoreRecords | Flag indicating whether or not the list of activities in the response body is truncated by the last query parameter value. Valid values: * true: The list of activities in the response body is truncated by the last query parameter value. Repeating the request with a higher last query parameter value will return additional activities for this context and context instance. * false: The list of activities in the response body isn't truncated by the last query parameter value. No further activities are available for this context and context instance. {#actsub-GET-activities__ul_x24_sf4_ylb} Data type: String |
| result.message | Error message describing the problem encountered during request processing. Data type: String |
| result.status | HTTP status code returned for request. Valid values: Refer to Status Codes. Data type: Number |
| result.stream | Sys_id specified in request context query parameter. Located in the Activity Context \[sn_actsub_activity_context\] table. Data type: String |
| result.user | Sys_id specified in request context_instance query parameter. Located in the appropriate table for the activity context. Data type: String |
[ ]

### cURL request

Request the second and third activity records for a specific Contact, limiting to data from
2020:

    curl "https://instance.servicenow.com/api/now/actsub/activities\
    ?context=4a6a035a73d30010e37d71ef64f6a714\
    &context_instance=ddce70866f9331003b3c498f5d3ee417\
    &stFrom=1&last=3\
    &start_date=2020-01-01%2000:00:00&end_date=2020-12-31%2023:59:59" \
    --request GET \
    --header "Accept: application/json" \
    --user "username:password"

The response body includes the two requested activity records for the specified
Contact:

    {
      "result": {
        "hasMoreRecords": true,
        "activities": [
          {
            "subobject_table_name": "sn_customerservice_case",
            "source_table_name": "sn_customerservice_case",
            "content_fields": [
              {
                "value": "Test",
                "show_label": "false",
                "type": "string",
                "label": "Short description",
                "display_as_timeago": "false",
                "deeplink_to_subobject": "false"
              }
            ],
            "created": "2020-05-29 18:42:16",
            "activity_type_id": "baf0aace73530010e37d71ef64f6a748",
            "title": "Lamar Wilson created case",
            "subobject_sys_id": "1687360e8d819010f87705a074e52ac9",
            "icon": "clipboard_outline",
            "sys_id": "1687360e8d819010f87705a074e52ac9",
            "subheader_fields": [
              {
                "value": "CS0001007",
                "show_label": "false",
                "type": "string",
                "label": "Number",
                "display_as_timeago": "false",
                "deeplink_to_subobject": "true"
              },
              {
                "value": "2020-05-29 18:42:16",
                "show_label": "false",
                "type": "glide_date_time",
                "label": "Created",
                "display_as_timeago": "true",
                "deeplink_to_subobject": "false"
              },
              {
                "value": "",
                "show_label": "false",
                "type": "reference",
                "label": "Assigned to",
                "display_as_timeago": "false",
                "deeplink_to_subobject": "false"
              },
              {
                "value": "Lamar Wilson",
                "show_label": "false",
                "type": "reference",
                "label": "Contact",
                "display_as_timeago": "false",
                "deeplink_to_subobject": "false"
              }
            ]
          },
          {
            "subobject_table_name": "kb_knowledge",
            "source_table_name": "kb_use",
            "content_fields": [
              {
                "value": "How to Set Up a Broadband Router",
                "show_label": "false",
                "type": "string",
                "label": "Short description",
                "display_as_timeago": "false",
                "deeplink_to_subobject": "false"
              }
            ],
            "created": "2020-05-26 10:00:00",
            "activity_type_id": "4a8c329273d30010e37d71ef64f6a7c1",
            "title": "Lamar Wilson viewed knowledge article",
            "subobject_sys_id": "f855a0a89f011200550bf7b6077fcf4f",
            "icon": "document_outline",
            "sys_id": "b929dd5873941010e37d71ef64f6a719",
            "subheader_fields": [
              {
                "value": "KB0000110",
                "show_label": "false",
                "type": "string",
                "label": "Number",
                "display_as_timeago": "false",
                "deeplink_to_subobject": "true"
              },
              {
                "value": "2020-05-26 10:00:00",
                "show_label": "false",
                "type": "glide_date_time",
                "label": "Created",
                "display_as_timeago": "true",
                "deeplink_to_subobject": "false"
              }
            ]
          }
        ]
      }
    }

## ActivitySubscriptions - GET
/now/actsub/facets/{activity_context}/{context_instance} {#ariaid-title5}

Retrieves facets configured for an activity context from the Subscriptions and Activity
Feed Framework. Displays activity counts and data for each facet as determined by activity type,
group, and context settings.
Users must have the actsub_user or admin role to access this endpoint. Data returned is
limited by user access settings.

For more details on activity context facets, see [Create facets for activity contexts](https://www.servicenow.com/docs/access?context=create-facet-customer-central&version=xanadu&pubname=xanadu-customer-service-management&ft:locale=en-US).

### URL format

Versioned URL:
/api/now/{api_version}/actsub/facets/{activity_context}/{context_instance}

Default URL:
/api/now/actsub/facets/{activity_context}/{context_instance}

### Supported request parameters

{#actsub-GET-facets__entry__2}{#actsub-GET-facets__version-not_optional-RESTAPI}

| Name | Description |
|-|-|
| activity_context | Sys_id of an activity context. Located in the Activity Contexts \[sn_actsub_activity_context\] table. Predefined activity contexts include Consumer and Contact. Navigate to Customer CentralCustomer ActivityActivity Contexts to view the full list of activity contexts defined for your instance. Data type: String |
| api_version | Optional. Version of the endpoint to access. For example, <kbd class="ph userinput">v1</kbd> or <kbd class="ph userinput">v2</kbd>. Only specify this value to use an endpoint version other than the latest. Data type: String |
| context_instance | Sys_id of an instance of the specified activity context, representing the initiator of the activities you want to retrieve facets for. Located in the context table specified for the activity context record in the Activity Contexts \[sn_actsub_activity_context\] table. As an example, if you set activity_context to the sys_id of the Contact activity context, you should set this parameter to the sys_id of the Contact \[customer_contact\] record for the contact whose activity facets you want to retrieve. Data type: String |
[Table 13. Path parameters]

{#actsub-GET-facets__entry__10}{#actsub-GET-facets__end-date-query-param-entry}{#actsub-GET-facets__start-date-query-param-entry}

| Name | Description |
|-|-|
| end_date | Date/time value. The request returns only records created during the time period defined by start_date and this parameter. Must be set along with start_date. Data type: String Format: YYYY-MM-DD hh:mm:ss or YYYY-MM-DD |
| facets | Comma-separated list of sys_ids of activity facets to retrieve for the specified activity context. To see the activity facet types defined for an activity context, navigate to Customer CentralCustomer ActivityActivity Contexts and examine the Facets related list. Data type: String Default: Return all activity facets configured for the activity context. |
| get_activity_count | Flag indicating whether or not to include activity counts for each facet in the response body. Valid values: * true: Include facet activity counts. * false: Omit facet activity counts. {#actsub-GET-facets__ul_zw1_y5n_ylb} Data type: Boolean Default: false |
| lazy_load | Flag indicating whether or not to improve performance by omitting facet activity data and activity counts from the response body. This parameter takes precedence over get_activity_count. Valid values: * true: Omit facet activity data and activity counts. * false: Retrieve facet activity data and activity counts. {#actsub-GET-facets__ul_ph3_kvn_ylb} Data type: Boolean Default: false |
| start_date | Date/time value. The request returns only records created during the time period defined by this parameter and end_date. Must be set along with end_date. Data type: String Format: YYYY-MM-DD hh:mm:ss or YYYY-MM-DD |
[Table 14. Query parameters]

{#actsub-GET-facets__entry__22}

| Name | Description |
|-|-|
| None |   |
[Table 15. Request body parameters (XML or JSON)]

### Headers

The following request and response headers apply to this HTTP
action only, or apply to this action in a distinct way. For a list of general headers used
in the REST API, see [Supported REST API headers](https://servicenow-prod.fluidtopics.net/2vuQj3~2s_niNXyXhrbRZA "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other.").
{#actsub-GET-facets__entry__26}{#actsub-GET-facets__accept-RESTAPI}

| Header | Description |
|-|-|
| Accept | Data format of the response body. Supported types: application/json or application/xml. Default: application/json |
[Table 16. Request headers]

{#actsub-GET-facets__entry__30}

| Header | Description |
|-|-|
| None |   |
[Table 17. Response headers]

### Status codes

The following status codes apply to this HTTP action. For a
list of possible status codes used in the REST API, see [REST API HTTP response
codes](https://servicenow-prod.fluidtopics.net/2vuQj3~2s_niNXyXhrbRZA "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other.").
{#actsub-GET-facets__entry__34}{#actsub-GET-facets__entry-200-status-code}{#actsub-GET-facets__entry-400-status-code}{#actsub-GET-facets__entry-401-status-code}{#actsub-GET-facets__entry-500-status-code}

| Status code | Description |
|-|-|
| 200 | Successful. The request was successfully processed. |
| 400 | Bad Request. A bad request type or malformed request was detected. The response body result.message parameter describes the nature of the error. Example error messages: * Make sure a valid activity context details are passed indicates that the activity_context path parameter value does not represent a valid activity context, the context_instance path parameter value does not represent a valid instance of the specified activity context, or both. * Please provide start_date and end_date indicates that the request includes only one of the start_date and end_date query parameters, which cannot be used separately. * start_date can not be ahead of end_date indicates that the specified start_date query parameter value occurs after the specified end_date query parameter value. {#actsub-GET-facets__ul_cvl_5c4_ylb} |
| 401 | Unauthorized. The user credentials are incorrect or have not been passed. |
| 500 | Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error. |
[Table 18. Status codes]

### Response body parameters (JSON or XML)

{#actsub-GET-facets__entry__44}

| Name | Description |
|-|-|
| result | List of activity facets. Data type: Array of Objects "result": [ { "activity_count": Number, "children": [Array], "facets": [Array], "icon": "String", "is_dynamic": "String", "message": "String", "name": "String", "status": Number } ] |
| result.activity_count | Number of activity records included in this facet (and its children, if any. Only displayed when lazy_load query parameter is false and get_activity_count query parameter is true. Data type: Number |
| result.children | Array of objects in which each object represents an activity record (if this is a dynamic facet) or a child facet (if this is a static facet). Data type: Array of Objects "children": [ { "activity_count": Number "facet": "String", "icon": "String", "title": "String" } ] |
| result.children.activity_count | Number of activity records included in this child facet (and its children, if any). Only displayed when the lazy_load query parameter is false and the get_activity_count query parameter is true. Data type: Number |
| result.children.created | Creation date/time for this activity record. Data type: String Format: YYYY-MM-DD hh:mm:ss |
| result.children.facet | Sys_id of this child facet record. Located in the Activity Facet \[sn_actsub_facet\] table. Data type: String |
| result.children.icon | Name of the icon associated with this child facet. Data type: String |
| result.children.sys_id | Sys_id of this activity record. Located in the appropriate table for the parent facet type. As an example, an activity record included in the Cases facet has a sys_id located in the Case \[sn_customerservice_case\] table. Data type: String |
| result.children.metadata | Array of objects in which each object includes activity record data for a facet field configured in the Activity Facet \[sn_actsub_facet\] table record for this facet type. Data type: Array of Objects "metadata": [ { "key": "String", "label": "String", "type": "String", "value": "String" } ] |
| result.children.metadata.key | Name of this facet field. Data type: String |
| result.children.metadata.label | Label of this facet field. Data type: String |
| result.children.metadata.type | Type of this facet field. Data type: String |
| result.children.metadata.value | Value of this facet field. Data type: String |
| result.children.title | Name of this activity record or child facet. Data type: String |
| result.facets | Array of sys_ids associated with this facet record. Located in the Activity Facet \[sn_actsub_facet\] table. For a dynamic facet, this array contains the sys_id of the facet itself. For a static facet, it instead contains the sys_ids of all facets which are children of the facet. Data type: Array "facets": [ "510d7e2e73570010e37d71ef64f6a70d", "bc9bfaaa73570010e37d71ef64f6a771" ] |
| result.icon | Name of the icon associated with this facet. Data type: String |
| result.is_dynamic | Flag indicating whether or not this facet is a dynamic facet. This value determines the type of information included in the children response body parameter. Possible values: * true: This is a dynamic facet. The children response body parameter value contains activity record details, and the facets parameter contains the dynamic facet sys_id. * false: This is a static facet (a facet group). The children response body parameter value contains child facets, and the facets parameter contains the sys_ids of these child facets. {#actsub-GET-facets__ul_atr_gnv_ylb} Data type: Boolean |
| result.message | Error message describing problem encountered during request processing. Data type: String |
| result.name | Name of the facet or facet group. Data type: String |
| result.status | HTTP status code returned for request. Possible values: See the Status Code table. Data type: Number |
[ ]

### cURL request

Retrieve Chat, Phone, and Knowledge articles facets and activity counts for a Contact:

    curl "https://instance.servicenow.com/api/now/actsub/facets/4a6a035a73d30010e37d71ef64f6a714/ddce70866f9331003b3c498f5d3ee417\
    ?get_activity_count=true\
    &facets=510d7e2e73570010e37d71ef64f6a70d,bc9bfaaa73570010e37d71ef64f6a771,c72d7e2e73570010e37d71ef64f6a7b8" \
    --request GET \
    --header "Accept: application/json" \
    --user "username:password"

The response body includes the three requested facets as children of their facet groups,
with activity counts displayed:

    {
      "result": [
        {
          "is_dynamic": false,
          "name": "Interactions",
          "activity_count": 4.0,
          "facets": [
            "510d7e2e73570010e37d71ef64f6a70d",
            "bc9bfaaa73570010e37d71ef64f6a771"
          ],
          "children": [
            {
              "facet": "510d7e2e73570010e37d71ef64f6a70d",
              "icon": "chat_outline",
              "activity_count": 2.0,
              "title": "Chat"
            },
            {
              "facet": "bc9bfaaa73570010e37d71ef64f6a771",
              "icon": "phone_outline",
              "activity_count": 2.0,
              "title": "Phone"
            }
          ]
        },
        {
          "is_dynamic": false,
          "name": "Portal Activity",
          "activity_count": 5.0,
          "facets": [
            "c72d7e2e73570010e37d71ef64f6a7b8"
          ],
          "children": [
            {
              "facet": "c72d7e2e73570010e37d71ef64f6a7b8",
              "icon": "document_outline",
              "activity_count": 5.0,
              "title": "Knowledge articles"
            }
          ]
        }
      ]
    }

*[\>]: and then