# Raw Crontab

**Page:** api/cron/crontab

[Download Raw Markdown](./api/cron/crontab.md)

---

{/* AUTO-GENERATED — Do not edit manually. Regenerate with: npm run docs:api:generate */}



## Raw Crontab

The Raw Crontab API provides low-level access to the system `crontab` for a given user. Use these endpoints to read the full crontab contents for a user, list the crontabs available across all users, and overwrite a user's crontab with a raw payload. These endpoints are useful when you need to inspect or bulk-replace a crontab without going through the managed entry endpoints.

## List all user crontabs

`GET /crontab`

Returns a paginated list of crontab entries for every user known to the system.

### Parameters

| Name   | In    | Type    | Required | Description           |
| ------ | ----- | ------- | -------- | --------------------- |
| `page` | query | integer | No       | Page number (1-based) |
| `limit` | query | integer | No       | Items per page (max 200) |



```bash
curl -X GET "https://api.example.com/api/cron/crontab/?page=1&limit=50" \
  -H "Authorization: Bearer <token>"
```


```javascript
const page = await client.cron.crontab.listGlobalIterator({ page: 1, limit: 50 });
for await (const crontab of page) {
  console.log(crontab);
}
```


```json
{
  "items": [
    {
      "crontab": "# m h dom mon dow command\n0 2 * * * /usr/local/bin/backup.sh",
      "user": "root"
    },
    {
      "crontab": "# m h dom mon dow command\n*/15 * * * * /usr/local/bin/healthcheck.sh",
      "user": "www-data"
    }
  ],
  "limit": 50,
  "page": 1,
  "total": 2
}
```


```json
{
  "code": "BACKEND_ERROR",
  "details": null,
  "message": "Internal server error"
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `BACKEND_ERROR` | Backend error | Failed to read or write system crontab | Check crontab availability and permissions |



## Get a user's crontab

`GET /users/{user}/crontab`

Returns the raw crontab contents for a single system user.

### Parameters

| Name   | In   | Type   | Required | Description      |
| ------ | ---- | ------ | -------- | ---------------- |
| `user` | path | string | Yes      | System username  |



```bash
curl -X GET "https://api.example.com/api/cron/crontab/users/root/crontab" \
  -H "Authorization: Bearer <token>"
```


```javascript
const crontab = await client.cron.crontab.get({ user: "root" });
console.log(crontab.crontab);
```


```json
{
  "crontab": "# m h dom mon dow command\n0 2 * * * /usr/local/bin/backup.sh",
  "user": "root"
}
```


```json
{
  "code": "INVALID_USER",
  "details": null,
  "message": "Invalid user"
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `INVALID_USER` | Invalid user | User parameter failed validation | Provide a valid system username |
| `INVALID_COMMENT` | Invalid comment | Comment is empty, too long, or contains newlines | Provide a short single-line comment |
| `INVALID_SCHEDULE` | Invalid schedule | Schedule is not a valid cron expression | Use a standard 5-field cron expression or @daily style macros |
| `INVALID_COMMAND` | Invalid command | Command field is empty or contains invalid characters | Provide a command without newlines |
| `INVALID_PAGINATION` | Invalid pagination | Page or limit is out of range | Use page 1 or higher and limit between 1 and 200 |


```json
{
  "code": "USER_NOT_FOUND",
  "details": null,
  "message": "User not found"
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `USER_NOT_FOUND` | User not found | The requested system user does not exist | Create the user or choose an existing username |
| `ENTRY_NOT_FOUND` | Entry not found | No managed entry with the provided id exists | List entries and retry with a valid id |


```json
{
  "code": "BACKEND_ERROR",
  "details": null,
  "message": "Internal server error"
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `BACKEND_ERROR` | Backend error | Failed to read or write system crontab | Check crontab availability and permissions |



## Update a user's crontab

`PUT /users/{user}/crontab`

Replaces the crontab for the given user with the supplied raw contents. Returns the updated crontab and the number of expired entries that were pruned during the operation.

### Parameters

| Name   | In   | Type   | Required | Description      |
| ------ | ---- | ------ | -------- | ---------------- |
| `user` | path | string | Yes      | System username  |



```bash
curl -X PUT "https://api.example.com/api/cron/crontab/users/root/crontab" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "crontab": "# m h dom mon dow command\n0 2 * * * /usr/local/bin/backup.sh"
  }'
```


```javascript
const result = await client.cron.crontab.put({
  user: "root",
  data: {
    crontab: "# m h dom mon dow command\n0 2 * * * /usr/local/bin/backup.sh"
  }
});
console.log(result.removed_expired);
```


```json
{
  "crontab": "# m h dom mon dow command\n0 2 * * * /usr/local/bin/backup.sh",
  "removed_expired": 0,
  "user": "root"
}
```


```json
{
  "code": "INVALID_USER",
  "details": null,
  "message": "Invalid user"
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `INVALID_USER` | Invalid user | User parameter failed validation | Provide a valid system username |
| `INVALID_COMMENT` | Invalid comment | Comment is empty, too long, or contains newlines | Provide a short single-line comment |
| `INVALID_SCHEDULE` | Invalid schedule | Schedule is not a valid cron expression | Use a standard 5-field cron expression or @daily style macros |
| `INVALID_COMMAND` | Invalid command | Command field is empty or contains invalid characters | Provide a command without newlines |
| `INVALID_PAGINATION` | Invalid pagination | Page or limit is out of range | Use page 1 or higher and limit between 1 and 200 |


```json
{
  "code": "USER_NOT_FOUND",
  "details": null,
  "message": "User not found"
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `USER_NOT_FOUND` | User not found | The requested system user does not exist | Create the user or choose an existing username |
| `ENTRY_NOT_FOUND` | Entry not found | No managed entry with the provided id exists | List entries and retry with a valid id |


```json
{
  "code": "PAYLOAD_TOO_LARGE",
  "details": null,
  "message": "Crontab payload exceeds the maximum allowed size"
}
```


```json
{
  "code": "BACKEND_ERROR",
  "details": null,
  "message": "Internal server error"
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `BACKEND_ERROR` | Backend error | Failed to read or write system crontab | Check crontab availability and permissions |




The `PUT /users/{user}/crontab` endpoint replaces the user's entire crontab. Any managed entries not included in the payload will be removed from the system crontab on the next reconciliation.