# Get Tenant Consumption Summary by Tenant

> POST endpoint for retrieving the consumption summary for a specific tenant, with breakdown by tenant-pool and organization-pool usage and an optional allocated quantity.

Use this endpoint to retrieve the consumption summary for a specific tenant in your organization.

## API endpoint

`POST` `{accessURL}/lease_/api/usage/{organizationId}/tenants/{tenantId}/consumption-summary`

Replace `{accessURL}` in all endpoint paths with the base URL for your cloud platform:

| Cloud platform | Access URL |
| --- | --- |
| Test Cloud | `https://cloud.uipath.com/` |
| Test Cloud Public Sector | `https://govcloud.uipath.us/` |
| Test Cloud Dedicated | `https://{customURL}.dedicated.uipath.com/` |

:::note
Your organization's name appears in the URL right after the access URL when you're logged into the product, for example `{accessURL}/{organizationName}/...`.
:::

## Request headers

```
--header 'Authorization: Bearer {access_token}'
--header 'Content-Type: application/json'
```

:::note
To obtain the `{access_token}`, make sure to authenticate through the ROPC method described [here](https://docs.uipath.com/test-cloud/automation-cloud/latest/api-guide/authentication-methods#authentication-methods).
:::

## Path parameters

| Path param | Data type | Description |
| --- | --- | --- |
| `organizationId` (required) | String (GUID) | The ID of the organization in which your tenant resides. |
| `tenantId` (required) | String (GUID) | The ID of the tenant for which to retrieve the consumption summary. |

## Request body

The request body specifies the date range and the consumable code for which to retrieve the summary. The tenant is determined by the `{tenantId}` path parameter.
For a detailed list of consumable codes, refer to [Consumables](https://docs.uipath.com/test-cloud/automation-cloud/latest/api-guide/license-codes).

```json
{
  "startDate": 0,
  "endDate": 0,
  "consumableCode": "string",
  "includeAllocation": false
}
```

| Field | Data type | Description |
| --- | --- | --- |
| `startDate` (required) | Long | Start of the date range, as a Unix timestamp in seconds. Values in milliseconds are rejected with a `400 Bad Request` error. |
| `endDate` (required) | Long | End of the date range, as a Unix timestamp in seconds. Values in milliseconds are rejected with a `400 Bad Request` error. |
| `consumableCode` (required) | String | The consumable to summarize. For robot units, use `RU`. |
| `includeAllocation` | Boolean | Defaults to `false`. When `true`, the response includes the tenant's allocated quantity for the consumable over the date range. |
| `tenantId` | String (GUID) | Don't send this field. The `{tenantId}` path parameter determines the tenant and overrides any value in the body. |
| `includeTopUpBreakdown` | Boolean | Not supported on this endpoint and always treated as `false`. To retrieve top-up consumption, use [Get Tenant Consumption Summary](get-tenant-consumption-summary.md). |

## Responses

### 200 OK

Returns the consumption summary for the specified tenant and, when requested, the tenant's allocated quantity.

| Field | Data type | Description |
| --- | --- | --- |
| `allocated` | Number | The tenant's allocated quantity for the consumable. Returned only when `includeAllocation` is `true`. |
| `consumedFromOrgWithoutTenant` | Number | Always `0` on this endpoint, because consumption without tenant context isn't attributed to any tenant. |
| `consumedByTopUp` | Number | Always `null` on this endpoint, because top-up breakdown isn't supported per tenant. |
| `tenantConsumptionItems[].tenantId` | String (GUID) | The ID of the tenant. |
| `tenantConsumptionItems[].consumedFromTenantPool` | Number | Units consumed from the tenant's allocation. |
| `tenantConsumptionItems[].consumedFromOrgPool` | Number | Units consumed from the organization pool. |
| `tenantConsumptionItems[].consumedByTopUp` | Number | Always `null` on this endpoint. |

:::note
Handle a `null` value in `allocated` as unknown, not as zero. `allocated` is `null` when the tenant has no license for the queried consumable, or when the date range spans more than one allocation period, such as a 90-day range when allocations are set monthly. A value of `0` means the tenant's allocation is zero.
:::

## Example request

The call should resemble the following example (cURL):

```
curl --location --request POST 'https://cloud.uipath.com/lease_/api/usage/11111111-1111-1111-1111-111111111111/tenants/22222222-2222-2222-2222-222222222222/consumption-summary' \
--header 'Authorization: Bearer <your-access-token>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "startDate": 1704067200,
  "endDate": 1706745600,
  "consumableCode": "consumption_unit_code",
  "includeAllocation": true
}'
```

Here's the response body for a successful consumption summary retrieval:

```json
{
  "consumedFromOrgWithoutTenant": 0,
  "consumedByTopUp": null,
  "allocated": 200,
  "tenantConsumptionItems": [
    {
      "tenantId": "string",
      "consumedFromTenantPool": 150,
      "consumedFromOrgPool": 0,
      "consumedByTopUp": null
    }
  ]
}
```