# Get head and lock ``` POST https://api.apify.com/v2/request-queues/:queueId/head/lock ``` Returns the given number of first requests from the queue and locks them for the given time. If this endpoint locks the request, no other client or run will be able to get and lock these requests. The response contains the `hadMultipleClients` boolean field which indicates that the queue was accessed by more than one client (with unique or empty `clientKey`). ## Request ### Path Parameters * **queueId** string required Queue ID or `username~queue-name`. **Example:** `WkzbQMuFYuamGv3YF` ### Query Parameters * **lockSecs** double required How long the requests will be locked for (in seconds). **Example:** `60` **limit** double **Possible values:** `<= 25` How many items from the queue should be returned. **Example:** `25` **clientKey** string A unique identifier of the client accessing the request queue. It must be a string between 1 and 32 characters long. This identifier is used to determine whether the queue was accessed by multiple clients. If `clientKey` is not provided, the system considers this API call to come from a new client. For details, see the `hadMultipleClients` field returned by the operation. **Example:** `client-abc` ### Status 200 **Response Headers** ``` { "data": { "limit": 3, "queueModifiedAt": "2018-03-14T23:00:00.000Z", "hadMultipleClients": true, "lockSecs": 60, "items": [ { "id": "8OamqXBCpPHxyj9", "retryCount": 0, "uniqueKey": "http://example.com", "url": "http://example.com", "method": "GET", "lockExpiresAt": "2022-06-14T23:00:00.000Z" }, { "id": "8OamqXBCpPHxyx9", "retryCount": 0, "uniqueKey": "http://example.com/a", "url": "http://example.com/a", "method": "GET", "lockExpiresAt": "2022-06-14T23:00:00.000Z" }, { "id": "8OamqXBCpPHxy08", "retryCount": 0, "uniqueKey": "http://example.com/a/b", "url": "http://example.com/a/b", "method": "GET", "lockExpiresAt": "2022-06-14T23:00:00.000Z" } ] } } ``` **Schema** * **data** object required A batch of locked requests from the request queue head. * **limit** integer required The maximum number of requests returned. **Example:** `1000` * **queueModifiedAt** string\ required The timestamp when the request queue was last modified. Modifications include adding, updating, or removing requests, as well as locking or unlocking requests. **Example:** `2018-03-14T23:00:00.000Z` * **queueHasLockedRequests** boolean Whether the request queue contains requests locked by any client (either the one calling the endpoint or a different one). **Example:** `true` * **clientKey** string The client key used for locking the requests. **Example:** `client-one` * **hadMultipleClients** boolean required Whether the request queue has been accessed by multiple different clients. **Example:** `true` * **lockSecs** integer required The number of seconds the locks will be held. **Example:** `60` * **items** object\[] required The array of locked requests from the request queue head. * **id** string required A unique identifier assigned to the request. **Example:** `8OamqXBCpPHxyH9` * **uniqueKey** string required A unique key used for request de-duplication. Requests with the same unique key are considered identical. **Example:** `GET|60d83e70|e3b0c442|https://apify.com` * **url** string\ required The URL of the request. **Example:** `https://apify.com` * **method** string The HTTP method of the request. **Example:** `GET` * **retryCount** integer The number of times this request has been retried. **Example:** `0` * **lockExpiresAt** string\ required The timestamp when the lock on this request expires. **Example:** `2022-06-14T23:00:00.000Z` ### Status 400 Bad request - invalid input parameters or request body. ``` { "error": { "type": "invalid-input", "message": "Invalid input: The request body contains invalid data." } } ``` **Schema** * **error** object required * **type** string required\ **Example:** `run-failed` * **message** string required\ **Example:** `Actor run did not succeed (run ID: 55uatRrZib4xbZs, status: FAILED)` ### Status 401 Unauthorized - authentication required or invalid token. ``` { "error": { "type": "token-not-valid", "message": "Authentication token is not valid." } } ``` **Schema** * **error** object required * **type** string required\ **Example:** `run-failed` * **message** string required\ **Example:** `Actor run did not succeed (run ID: 55uatRrZib4xbZs, status: FAILED)` ### Status 403 Forbidden - insufficient permissions to perform this action. ``` { "error": { "type": "permission-denied", "message": "You do not have permission to perform this action." } } ``` **Schema** * **error** object required * **type** string required\ **Example:** `run-failed` * **message** string required\ **Example:** `Actor run did not succeed (run ID: 55uatRrZib4xbZs, status: FAILED)` ### Status 404 Not found - the requested resource was not found. ``` { "error": { "type": "record-not-found", "message": "Request Queue was not found" } } ``` **Schema** * **error** object * **type** string **Possible values:** \[`record-not-found`] * **message** string\ **Example:** `Request Queue was not found` ### Status 405 Method not allowed. ``` { "error": { "type": "method-not-allowed", "message": "This API end-point can only be accessed using the following HTTP methods: OPTIONS,GET" } } ``` **Schema** * **error** object required * **type** string required\ **Example:** `run-failed` * **message** string required\ **Example:** `Actor run did not succeed (run ID: 55uatRrZib4xbZs, status: FAILED)` ### Status 429 Too many requests - rate limit exceeded. ``` { "error": { "type": "rate-limit-exceeded", "message": "You have exceeded the rate limit. Please try again later." } } ``` **Schema** * **error** object required * **type** string required\ **Example:** `run-failed` * **message** string required\ **Example:** `Actor run did not succeed (run ID: 55uatRrZib4xbZs, status: FAILED)`