Get copilotPolicySetting

Read the properties of a copilotPolicySetting object.

Retrieve the current value of a Copilot policy setting by its identifier. The API resolves the correct underlying policy service (CPS or Intune) and returns the setting value along with the associated policy ID.

Permissions

Choose the permission or permissions marked as least privileged for this API. Use a higher privileged permission or permissions only if your app requires it. For details about delegated and application permissions, see Permission types. To learn more about these permissions, see the permissions reference.

HTTP request

GET https://graph.microsoft.com/beta/copilot/admin/policySettings/{id}

Path parameters

Optional query parameters

This method supports the $select OData query parameter to help customize the response. For general information, see OData query parameters.

Request headers

Request body

Don't supply a request body for this method.

Response

If successful, this method returns a 200 OK response code and a copilotPolicySetting object in the response body.

When the setting isn't configured or no tenant-level policy exists, the API returns 200 OK with value and/or policyId set to null.

Examples

Example 1: Get a configured setting

The following example shows how to retrieve a Copilot setting that is configured with a value in a tenant-level policy.

Request

The following example shows a request.

GET https://graph.microsoft.com/beta/copilot/admin/policySettings/microsoft.copilot.copilotchatpinning

Response

The following example shows the response.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#copilot/admin/policySettings/$entity",
  "@odata.type": "#microsoft.graph.copilotPolicySetting",
  "id": "microsoft.copilot.copilotchatpinning",
  "value": "1",
  "policyId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Example 2: Get an unconfigured setting

The following example shows how to retrieve a setting where a tenant-level policy exists but the setting value isn't configured. The API returns 200 OK with value as null.

Request

The following example shows a request.

GET https://graph.microsoft.com/beta/copilot/admin/policySettings/microsoft.copilot.imagegeneration

Response

The following example shows the response.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#copilot/admin/policySettings/$entity",
  "@odata.type": "#microsoft.graph.copilotPolicySetting",
  "id": "microsoft.copilot.imagegeneration",
  "value": null,
  "policyId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Example 3: Get a setting when no policy exists

The following example shows how to retrieve a setting where no tenant-level policy is created yet. The API returns 200 OK with both value and policyId as null.

Request

The following example shows a request.

GET https://graph.microsoft.com/beta/copilot/admin/policySettings/microsoft.copilot.allowwebsearch

Response

The following example shows the response.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#copilot/admin/policySettings/$entity",
  "@odata.type": "#microsoft.graph.copilotPolicySetting",
  "id": "microsoft.copilot.allowwebsearch",
  "value": null,
  "policyId": null
}

Example 4: Get a setting scoped to a group-level policy

The following example shows a request for a supported setting that is configured in a group-level policy, which this endpoint doesn't support. The API returns 422 Unprocessable Content.

Request

The following example shows a request.

GET https://graph.microsoft.com/beta/copilot/admin/policySettings/microsoft.copilot.copilotchatpinning

Response

The following example shows the response.

HTTP/1.1 422 Unprocessable Content
Content-Type: application/json

{
  "error": {
    "code": "unprocessableEntity",
    "message": "The setting 'microsoft.copilot.copilotchatpinning' is scoped to a group-level policy, which is not supported by this endpoint. Only tenant-level policy settings are supported.",
    "innerError": {
      "code": "groupScopedSettingNotSupported",
      "request-id": "00000000-0000-0000-0000-000000000003",
      "date": "2026-04-06T13:37:18",
      "client-request-id": "00000000-0000-0000-0000-000000000004"
    }
  }
}

Example 5: Get an unsupported setting

The following example shows a request for a setting identifier that isn't in the supported list. The API returns 404 Not Found.

Request

The following example shows a request.

GET https://graph.microsoft.com/beta/copilot/admin/policySettings/microsoft.copilot.pinning

Response

The following example shows the response.

HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "error": {
    "code": "notFound",
    "message": "The setting 'microsoft.copilot.pinning' is not supported. Only supported Copilot settings can be accessed through this endpoint.",
    "innerError": {
      "code": "unsupportedSetting",
      "request-id": "00000000-0000-0000-0000-000000000001",
      "date": "2026-04-06T13:37:18",
      "client-request-id": "00000000-0000-0000-0000-000000000002"
    }
  }
}

Example 6: Get a setting when the tenant has too many group policies

The following example shows a request for a setting when the number of group-level policies in the tenant exceeds the supported limit. The API returns 502 Bad Gateway.

Request

The following example shows a request.

GET https://graph.microsoft.com/beta/copilot/admin/policySettings/microsoft.copilot.copilotchatpinning

Response

The following example shows the response.

HTTP/1.1 502 Bad Gateway
Content-Type: application/json

{
  "error": {
    "code": "badGateway",
    "message": "The operation could not be completed because the number of group-level policies exceeds the supported limit.",
    "innerError": {
      "code": "tooManyGroupPolicies",
      "request-id": "00000000-0000-0000-0000-000000000005",
      "date": "2026-04-13T11:16:52",
      "client-request-id": "00000000-0000-0000-0000-000000000006"
    }
  }
}