Get head and lock

POST 
/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.

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<date-time> 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<uri> 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<date-time> 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)