# Elastic access request in the context of a session Makes an elastic access request in the context of a session. Endpoint: PUT /api/v1.1/sessions/{sessionId} Version: v1.1 Security: AdministrationAccess, ClientAccess ## Security: - `AdministrationAccess` (unknown) http bearer JWT - `ClientAccess` (unknown) http bearer JWT ## Path parameters: - `sessionId` (string, required) UUID of the session where the access request is being made. ## Header parameters: - `x-instance-id` (string) UUID of the instance the session is linked to. Required by requests that use a ClientAccess token. - `correlationId` (string) An optional identifier for the request. If provided, it is recommended to use a UUID format to minimise the risk of reusing the same correlationId. This field can be used to support safe retries, typically when the request has timed out. The safe retry configuration option must be enabled first, refer to the Configuration section for more information on how to enable this. If no correlationId is supplied, Dynamic Monetization will generate one automatically. ## Request body: - `application/json` (unknown) The information required in the request payload. ## Request fields (application/json): - `requester` (object, required) Requester details - `requester.type` (string) Type of the requester. - `requester.value` (string) Unique identifier for the requester. - `rollbackOnDeny` (boolean, required) When true, if the request cannot be granted the session will revert to the combination of items it was charging for before the request was made. When false, if the request cannot be granted the session will refund all items it was charging for before the request was made, and the session state will be set to TERMINATED. The amount refunded will be calculated using the time of the denied request up until the end of the period that has been charged for. - `requestedItems` (array, required) A list of requested items. Provide an empty list to stop using all items. - `requestedItems.item` (string) The requested item. - `requestedItems.version` (string) The version of the item requested. This field may only be omitted or left blank if the intention is to access an item in a rate table with an empty or unspecified version. - `requestedItems.count` (number) Number of instances of the requested item required. The value can be fractional. - `requestedItems.variables` (object) A collection of named input values used for evaluating formula-based token consumption in an access request. Each key represents a variable identifier referenced in the configured rate table formula, and the corresponding value is the numeric input used to evaluate the formula. The `variables` field is mutually exclusive with the `count` field. Requests must include either `count` (for fixed-rate) or `variables` (for formula-based), but not both. - At least one variable must be provided. - Variable names must match those defined in the formula. - Variable values must be numeric. - `requestedItems.metaData` (object) (Optional) For sending custom data with the request, which will be sent to the data warehouse with the usage information to assist with analyzing access activity. The meta data content must be a valid JSON object. ## Response 200: - `200` (unknown) OK. The request succeeded in its entirety. ## Response 200 fields (application/json): - `requestedItems` (array) List of requested items. - `requestedItems.count` (number) Number of instances of the requested item granted. The value can be fractional. - `requestedItems.variables` (object) The variables associated with the requested item that were used to calculate tokens required based on formula. Response will have either `count` or `variables` depending on what was sent in the request. - `requestedItems.item` (string) The name of a requested item. - `requestedItems.version` (string) The version of a requested item. - `requestedItems.totalTokensCharged` (number) Total number of tokens charged across all line items. The value can be fractional. - `requestedItems.lineItems` (array) List of line items charged to fulfill this request. - `requestedItems.lineItems.rate` (number) Rate applied. The value can be fractional. - `requestedItems.lineItems.formula` (string) The formula used to calculate the charge for this line item. This field is only applicable if the line item was charged based on a formula. If the charge was based on a fixed rate, this field will be absent. - `requestedItems.lineItems.activationId` (string) Activation ID of line item charged to fulfill the request. - `requestedItems.lineItems.tokensCharged` (number) Number of tokens charged. The value can be fractional. - `requestedItems.lineItems.actionId` (string) Unique identifier of the action and allocation used if the access request was fulfilled from an allocation within the line item. - `requestedItems.lineItems.consumptionLimitId` (string) Unique identifier of the consumption limit used when the access request was fulfilled from a consumption limit on the line item. Example: autoTracked - `requestedItems.status` (object) The response status to the request for the specific item. - `requestedItems.status.code` (string) Possible values * 1001 (Successfully checked out) * 1002 (No Status) * 2001 (Item not found in any effective rate table) * 3001 (No valid active line items) * 3006 (Insufficient count available) * 3007 (Requester consumption limit exceeded) * 4001 (Failed due to internal server error) There was an internal error processing the request. If you need to contact support, please include the correlationId provided in the response. - `requestedItems.status.description` (string) A user-readable message explaining the status code. Example: Successfully checked out. - `instanceConsumptionLimitId` (string) Unique identifier of the consumption limit used when the access request was fulfilled from a consumption limit on the instance. Example: autoTracked - `notifications` (object) Notification details for this access request when a consumption limit is configured with `notificationId` set to `accessResponseBody` and consumption crosses a configured threshold percentage of the consumption limit. If multiple thresholds are crossed while processing the request, the response includes only the highest threshold crossed. The same threshold can appear again in a later response if consumption drops below that threshold and subsequently crosses it again. - `notifications.instanceConsumptionLimit` (object) Notification details for the instance consumption limit. - `notifications.instanceConsumptionLimit.id` (string) Unique identifier of the instance consumption limit that triggered the notification. Example: autoTracked - `notifications.instanceConsumptionLimit.message` (string) Notification message describing the configured consumption threshold that was crossed and the current consumption percentage of the consumption limit after the access request was processed. Example: Requester usage has exceeded the 25% consumption limit threshold. Usage is currently at 25.5%. - `requester` (object) Requester details - `requester.type` (string) Type of the requester. - `requester.value` (string) Unique identifier for the requester. - `correlationId` (string) An ID which allows correlation of the request with usage information obtained from the data warehouse. ## Response 400: - `400` (unknown) Bad Request. Check the request for any errors in the input. ## Response 401: - `401` (unknown) Unauthorized. Check authentication details. ## Response 403: - `403` (unknown) The body may show how some item requests could have succeeded, but were not granted because the whole request had to be denied because it was an atomic request. ## Response 403 fields (application/json): - `requestedItems` (array) List of requested items. - `requestedItems.count` (number) Number of instances of the requested item granted. The value can be fractional. - `requestedItems.variables` (object) The variables associated with the requested item that were used to calculate tokens required based on formula. Response will have either `count` or `variables` depending on what was sent in the request. - `requestedItems.item` (string) The name of a requested item. - `requestedItems.version` (string) The version of a requested item. - `requestedItems.totalTokensCharged` (number) Total number of tokens charged across all line items. The value can be fractional. - `requestedItems.lineItems` (array) List of line items charged to fulfill this request. - `requestedItems.lineItems.rate` (number) Rate applied. The value can be fractional. - `requestedItems.lineItems.formula` (string) The formula used to calculate the charge for this line item. This field is only applicable if the line item was charged based on a formula. If the charge was based on a fixed rate, this field will be absent. - `requestedItems.lineItems.activationId` (string) Activation ID of line item charged to fulfill the request. - `requestedItems.lineItems.tokensCharged` (number) Number of tokens charged. The value can be fractional. - `requestedItems.lineItems.actionId` (string) Unique identifier of the action and allocation used if the access request was fulfilled from an allocation within the line item. - `requestedItems.lineItems.consumptionLimitId` (string) Unique identifier of the consumption limit used when the access request was fulfilled from a consumption limit on the line item. Example: autoTracked - `requestedItems.status` (object) The response status to the request for the specific item. - `requestedItems.status.code` (string) Possible values * 1001 (Successfully checked out) * 1002 (No Status) * 2001 (Item not found in any effective rate table) * 3001 (No valid active line items) * 3006 (Insufficient count available) * 3007 (Requester consumption limit exceeded) * 4001 (Failed due to internal server error) There was an internal error processing the request. If you need to contact support, please include the correlationId provided in the response. - `requestedItems.status.description` (string) A user-readable message explaining the status code. Example: Successfully checked out. - `instanceConsumptionLimitId` (string) Unique identifier of the consumption limit used when the access request was fulfilled from a consumption limit on the instance. Example: autoTracked - `notifications` (object) Notification details for this access request when a consumption limit is configured with `notificationId` set to `accessResponseBody` and consumption crosses a configured threshold percentage of the consumption limit. If multiple thresholds are crossed while processing the request, the response includes only the highest threshold crossed. The same threshold can appear again in a later response if consumption drops below that threshold and subsequently crosses it again. - `notifications.instanceConsumptionLimit` (object) Notification details for the instance consumption limit. - `notifications.instanceConsumptionLimit.id` (string) Unique identifier of the instance consumption limit that triggered the notification. Example: autoTracked - `notifications.instanceConsumptionLimit.message` (string) Notification message describing the configured consumption threshold that was crossed and the current consumption percentage of the consumption limit after the access request was processed. Example: Requester usage has exceeded the 25% consumption limit threshold. Usage is currently at 25.5%. - `requester` (object) Requester details - `requester.type` (string) Type of the requester. - `requester.value` (string) Unique identifier for the requester. - `correlationId` (string) An ID which allows correlation of the request with usage information obtained from the data warehouse. ## Response 404: - `404` (unknown) Resource not found. The requested resource is not available. ## Response 409: - `409` (unknown) Returned when the session is in one of the following states: FAILED, TERMINATED, or DISCONNECTED. In these cases, initiate a new session. If the session is LOCKED due to a resource conflict, retry the request. Sessions in a locked state typically become available shortly. ## Response 409 fields (application/json): - `message` (string) ## Response 500: - `500` (unknown) Internal Server Error. The session state will be set to FAILED. To resolve this, the client should initiate a new session. If you need to contact support, please include the reference number provided in the response. ## Response 503: - `503` (unknown) API is temporarily unavailable. Try again later.