# Add request ``` POST https://api.apify.com/v2/request-queues/:queueId/requests ``` Adds request to the queue. Response contains ID of the request and info if request was already present in the queue or handled. If request with same `uniqueKey` was already present in the queue then returns an ID of existing request. ## Request ### Path Parameters * **queueId** string required Queue ID or `username~queue-name`. **Example:** `WkzbQMuFYuamGv3YF` ### Query Parameters * **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` **forefront** string Determines if request should be added to the head of the queue or to the end. Default value is `false` (end of queue). **Example:** `false` ### Body**required** * **uniqueKey** UniqueKey (string) 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\ The URL of the request. **Example:** `https://apify.com` * **method** HttpMethod (string) **Possible values:** \[`GET`, `HEAD`, `POST`, `PUT`, `DELETE`, `CONNECT`, `OPTIONS`, `TRACE`, `PATCH`] **Example:** `GET` * **retryCount** RetryCount (integer) The number of times this request has been retried. **Example:** `0` * **loadedUrl** string,null\ nullable The final URL that was loaded, after redirects (if any). **Example:** `https://apify.com/jobs` * **payload** object | null nullable The request payload, typically used with POST or PUT requests. **Example:** `null` * **headers** object | null nullable HTTP headers sent with the request. **Example:** `null` * **userData** object Custom user data attached to the request. Can contain arbitrary fields. * **label** string | null nullable Optional label for categorizing the request. **Example:** `DETAIL` * **image** string,null\ nullable Optional image URL associated with the request. **Example:** `https://picserver1.eu` * **property name\*** any Custom user data attached to the request. Can contain arbitrary fields. * **noRetry** boolean | null nullable Indicates whether the request should not be retried if processing fails. **Example:** `false` * **errorMessages** string\[] nullable Error messages recorded from failed processing attempts. **Example:** `null` * **handledAt** string,null\ nullable The timestamp when the request was marked as handled, if applicable. **Example:** `2019-06-16T10:23:31.607Z` ### Status 201 **Response Headers** ``` { "data": { "requestId": "sbJ7klsdf7ujN9l", "wasAlreadyPresent": false, "wasAlreadyHandled": false } } ``` **Schema** * **data** object required Result of registering a request in the request queue, either by adding a new request or updating an existing one. * **requestId** RequestId (string) required A unique identifier assigned to the request. **Example:** `sbJ7klsdf7ujN9l` * **wasAlreadyPresent** WasAlreadyPresent (boolean) required Indicates whether a request with the same unique key already existed in the request queue. If true, no new request was created. **Example:** `false` * **wasAlreadyHandled** WasAlreadyHandled (boolean) required Indicates whether a request with the same unique key has already been processed by the request queue. **Example:** `false` ### 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 413 Payload too large - the request body exceeds the size limit. ``` { "error": { "type": "request-too-large", "message": "The POST payload is too large (limit: 9437184 bytes, actual length: 10485760 bytes)." } } ``` **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 415 Unsupported media type - the Content-Encoding of the request is not supported. ``` { "error": { "type": "unsupported-content-encoding", "message": "Content-Encoding \"bla\" is not supported." } } ``` **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)`