> ## Documentation Index
> Fetch the complete documentation index at: https://docs.screenshotmax.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Task

> Create a new scheduled task

It’s simple to use: you only need to submit your `access_key` and the payload. The API will return the new scheduled task created.

<Warning>
  **Plan Requirement**

  Scheduled Tasks are available only on the **Scale plan**.
  Upgrade your account via the Subscription / Dashboard [section](https://app.screenshotmax.com/subscribe/monthly) to unlock this feature.
</Warning>

<Note>Requests to this endpoint are **not counted against your usage quota,** but they are **still subject to rate limiting.** This ensures fair use and stability of the platform. If you exceed the rate limit, your requests may be temporarily blocked.</Note>

## Getting started

### REST

The Task API, like all of ScreenshotMAX’s APIs, is organized around REST. It is designed to use predictable, resource-oriented URL’s and to use HTTP status codes to indicate errors.

### HTTPS

The Task API requires all communications to be secured TLS 1.2 or greater.

### API Versions

All of ScreenshotMAX’s APIs are versioned. The Task API is currently on Version 1.

### Your Access Key

Your access key is your unique authentication key to be used to access ScreenshotMAX APIs.
To authenticate your requests, you will need to append your access key to the base URL as a query parameter for GET requests.
For POST and PATCH requests, you can include your access key in the request body as a JSON object.
You can also use the `X-Access-Key` header to pass your access key.
You can find your access key in your [account dashboard](https://app.screenshotmax.com/access).

### Base URL

```
https://api.screenshotmax.com/v1/tasks
```

### Validation endpoint

ScreenshotMAX’s Task API simply requires your unique access key. The API will return the list of your scheduled tasks for your account.

```json theme={null}
POST https://api.screenshotmax.com/v1/tasks
{
  "access_key": "YOUR_ACCESS_KEY",
  "name": "task screenshot",
  "api": "screenshot",
  "query": "url=https%3A%2F%2Fexample.com",
  "frequency": "every_month",
  "crontab": "34 9 28 * *",
  "timezone": "Etc/UTC",
  "enabled": true
}
```

This was a successful request, so the API returned a 201 OK response with the new scheduled task for your account.

```json theme={null}
{
  "id": 5650820808835072,
  "name": "task screenshot",
  "api": "screenshot",
  "query": "url=https%3A%2F%2Fexample.com",
  "frequency": "every_month",
  "crontab": "34 9 28 * *",
  "timezone": "Etc/UTC",
  "enabled": true,
  "created": 1714296566,
  "last_run": 1745832566,
  "runs": 12
}
```

### Body parameters

<ParamField body="access_key" type="string" required>
  Your unique access key. You can find your access key in your [account dashboard](https://app.screenshotmax.com/access).
</ParamField>

<ParamField body="name" type="string" required>
  Name of the scheduled task. The maximum length is 100 characters.
</ParamField>

<ParamField body="api" type="string" required>
  Api endpoint for the scheduled task. Available options are:

  * `screenshot`
  * `screencast`
  * `pdf`
  * `scrape`
</ParamField>

<ParamField body="query" type="string" required>
  Query parameters for the scheduled task without the `access_key` parameter.
  The querystring can be URL-encoded.

  For example, `url=https%3A%2F%2Fexample.com` is the URL-encoded version of `url=https://example.com`.
</ParamField>

<ParamField body="frequency" type="string" required>
  Frequency of the scheduled task. Available options are:

  * `every_minute`
  * `every_hour`
  * `every_day`
  * `every_month`
  * `custom` (use standard cron syntax)
</ParamField>

<ParamField body="crontab" type="string">
  **Optional** - Only available if the `frequency` is set to `custom`.
  Cron expression used to the scheduled task. You can create one easily using the [Unix Cron Format](http://crontab.org) with this tool [Unix Cron Generator](https://crontab-generator.com/en).

  The cron expression is a string that represents a schedule in the Unix cron format. It consists of five fields separated by spaces, each representing a different unit of time.
  The fields are:

  * minute (0-59)
  * hour (0-23)
  * day of the month (1-31)
  * month (1-12)
  * day of the week (0-6, where 0 is Sunday)
    The cron expression can also include special characters such as `*` (any value), `,` (list of values), `-` (range of values), and `/` (step values).

  For example, the cron expression `34 9 28 * *` means "run at 9:34 AM on the 28th day of every month".
</ParamField>

<ParamField body="timezone" type="string" default="Etc/UTC">
  Timezone for the scheduled task. Available time zones from the [IANA Time Zone Database](https://www.iana.org/time-zones).
</ParamField>

<ParamField body="enabled" type="boolean" default="true">
  Indicates if the scheduled task is enabled or disabled.
</ParamField>

### Response parameters

The API response is returned in a universal and lightweight [JSON format](https://www.json.org/json-en.html).

<ResponseField name="id" type="number">
  Unique identifier for the scheduled task. This ID is automatically generated when you create a new scheduled task.
</ResponseField>

<ResponseField name="name" type="string">
  Name of the scheduled task.
</ResponseField>

<ResponseField name="api" type="string">
  Service to be used for the scheduled task. Available options include `screenshot`, `screencast`, `pdf` and `scrape`.
</ResponseField>

<ResponseField name="query" type="string">
  Query parameters for the scheduled task without the `access_key` parameter.
  The querystring can be URL-encoded.

  For example, `url=https%3A%2F%2Fexample.com` is the URL-encoded version of `url=https://example.com`.
</ResponseField>

<ResponseField name="frequency" type="string">
  Frequency of the scheduled task. Available options are `every_minute`, `every_hour`, `every_day`, `every_month` and `custom` (use standard cron syntax).
</ResponseField>

<ResponseField name="crontab" type="string">
  Cron expression used to the scheduled task. Use [Unix Cron Format](https://crontab-generator.com/en)
</ResponseField>

<ResponseField name="timezone" type="string">
  Timezone for the scheduled task. Available time zones from the [IANA Time Zone Database](https://www.iana.org/time-zones).
</ResponseField>

<ResponseField name="enabled" type="boolean">
  Indicates if the scheduled task is enabled or disabled.
</ResponseField>

<ResponseField name="created" type="number">
  Unix timestamp in seconds when the scheduled task was created.
</ResponseField>

<ResponseField name="last_run" type="number">
  Unix timestamp in seconds when the scheduled task was last run.
</ResponseField>

<ResponseField name="runs" type="number">
  Number of times the scheduled task has run.
</ResponseField>

### Error Codes

Whenever you make a request that fails for some reason, an error is returned also in the JSON format. The errors include an error code and description, which you can find in detail below.

| Code | Type                  | Details                                                          |
| ---- | --------------------- | ---------------------------------------------------------------- |
| 201  | OK                    | The request was successful.                                      |
| 400  | Bad Request           | The request was rejected due to a missing or invalid parameter.  |
| 401  | Unauthorized          | The request was rejected due to an invalid access key.           |
| 402  | Payment Required      | Access denied due to an unpaid invoice.                          |
| 404  | Not Found             | The requested resource was not found.                            |
| 423  | Locked                | The request was denied due to insufficient quota.                |
| 429  | Too Many Requests     | The rate limit has been exceeded (too many requests per minute). |
| 500  | Internal server error | The request failed due to an internal server error.              |