# Cron job endpoint

`GET /v1/cron/{cliToken}`

Firefly III has one endpoint for its various cron related tasks. Send a GET to this endpoint
to run the cron. The cron requires the CLI token to be present. The cron job will fire for all
users.


Authentication (security requirement alternatives):

```json
[
  {
    "firefly_iii_auth": []
  },
  {
    "local_bearer_auth": []
  }
]
```

- firefly_iii_auth: oauth2. OAuth2 authorization code flow. Create a client on your installation's `/profile` page; it authorizes at `/oauth/authorize` and issues tokens at `/oauth/token` there. The URLs below are the demo site's. [How to use the API](https://sourcey-firefly.pages.dev/how-to/firefly-iii/features/api/index.md) walks through it.
- local_bearer_auth: http (bearer). A Personal Access Token, sent as a bearer token. Create one on your installation under Options > Profile > OAuth > Personal Access Tokens.

Parameters:

- `X-Trace-Id` (header, string, uuid, optional) - Unique identifier associated with this request.
  Type: string, uuid
  
  Example:
  
  ```json
  "40c71bbb-c676-4f24-83cf-cc725d7d7a00"
  ```

- `cliToken` (path, string, string, required) - The CLI token of any user in Firefly III, required to run the cron job. OR this is the `STATIC_CRON_TOKEN`.
  Type: string, string
  
  Example:
  
  ```json
  "d5ea6b5fb774618dd6ad6ba6e0a7f55c"
  ```

- `date` (query, string, date, optional) - A date formatted YYYY-MM-DD. This can be used to make the cron job pretend it's running
on another day.

  Type: string, date
  
  Example:
  
  ```json
  "2026-10-01"
  ```

- `force` (query, boolean, optional) - Forces the cron job to fire, regardless of whether it has fired before. This may result
in double transactions or weird budgets, so be careful. Only system owners can do this.

  Type: boolean
  
  Example:
  
  ```json
  false
  ```

Responses:

- 200: The result of the cron job(s) firing.

Content type: application/json

Type: object

Schema: [CronResult](https://sourcey-firefly.pages.dev/api/models/cronresult/index.md)

- `recurring_transactions` (optional)
  Type: array
  
  Items:
    Reference: [CronResultRow](https://sourcey-firefly.pages.dev/api/models/cronresultrow/index.md); Type: object

- `auto_budgets` (optional)
  Type: array
  
  Items:
    Reference: [CronResultRow](https://sourcey-firefly.pages.dev/api/models/cronresultrow/index.md); Type: object

- `exchange_rates` (optional)
  Type: array
  
  Items:
    Reference: [CronResultRow](https://sourcey-firefly.pages.dev/api/models/cronresultrow/index.md); Type: object

- `bill_notifications` (optional)
  Type: array
  
  Items:
    Reference: [CronResultRow](https://sourcey-firefly.pages.dev/api/models/cronresultrow/index.md); Type: object

- `webhooks` (optional)
  Type: array
  
  Items:
    Reference: [CronResultRow](https://sourcey-firefly.pages.dev/api/models/cronresultrow/index.md); Type: object

- 400: Bad request

Content type: application/json

Type: object

Schema: [BadRequestResponse](https://sourcey-firefly.pages.dev/api/models/badrequestresponse/index.md)

- `message` (optional)
  Type: string, string
  
  Example:
  
  ```json
  "Bad Request"
  ```

- `exception` (optional)
  Type: string, string
  
  Example:
  
  ```json
  "BadRequestHttpException"
  ```

- 401: Unauthenticated

Content type: application/json

Type: object

Schema: [UnauthenticatedResponse](https://sourcey-firefly.pages.dev/api/models/unauthenticatedresponse/index.md)

- `message` (optional)
  Type: string, string
  
  Example:
  
  ```json
  "Unauthenticated"
  ```

- `exception` (optional)
  Type: string, string
  
  Example:
  
  ```json
  "AuthenticationException"
  ```

- 404: Page not found

Content type: application/json

Type: object

Schema: [NotFoundResponse](https://sourcey-firefly.pages.dev/api/models/notfoundresponse/index.md)

- `message` (optional)
  Type: string, string
  
  Example:
  
  ```json
  "Resource not found"
  ```

- `exception` (optional)
  Type: string, string
  
  Example:
  
  ```json
  "NotFoundHttpException"
  ```

- 422: Validation error. The body will have the exact details.

Content type: application/json

Type: object

Schema: [ValidationErrorResponse](https://sourcey-firefly.pages.dev/api/models/validationerrorresponse/index.md)

- `message` (optional)
  Type: string, string
  
  Example:
  
  ```json
  "The given data was invalid."
  ```

- `errors` (optional)
  Type: object
  
  - `email` (optional)
    Type: array
    
    Items:
      Type: string, string
  
  - `force` (optional)
    Type: array
    
    Items:
      Type: string, string
  
  - `blocked` (optional)
    Type: array
    
    Items:
      Type: string, string
  
  - `field` (optional)
    Type: array
    
    Items:
      Type: string, string
  
  - `role` (optional)
    Type: array
    
    Items:
      Type: string, string
  
  - `blocked_code` (optional)
    Type: array
    
    Items:
      Type: string, string
  
  - `name` (optional)
    Type: array
    
    Items:
      Type: string, string
  
  - `type` (optional)
    Type: array
    
    Items:
      Type: string, string
  
  - `iban` (optional)
    Type: array
    
    Items:
      Type: string, string
  
  - `start` (optional)
    Type: array
    
    Items:
      Type: string, string
  
  - `end` (optional)
    Type: array
    
    Items:
      Type: string, string
  
  - `date` (optional)
    Type: array
    
    Items:
      Type: string, string

- 500: Internal exception

Content type: application/json

Type: object

Schema: [InternalExceptionResponse](https://sourcey-firefly.pages.dev/api/models/internalexceptionresponse/index.md)

- `message` (optional)
  Type: string, string
  
  Example:
  
  ```json
  "Internal Exception"
  ```

- `exception` (optional)
  Type: string, string
  
  Example:
  
  ```json
  "InternalException"
  ```

## Examples

### cURL

```bash
curl -X GET 'https://firefly.example.com/api/v1/cron/d5ea6b5fb774618dd6ad6ba6e0a7f55c' \
  -H 'X-Trace-Id: 40c71bbb-c676-4f24-83cf-cc725d7d7a00' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://firefly.example.com/api/v1/cron/d5ea6b5fb774618dd6ad6ba6e0a7f55c', {
  method: 'GET',
  headers: {
    'X-Trace-Id': '40c71bbb-c676-4f24-83cf-cc725d7d7a00',
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();
```

### Python

```python
import requests

response = requests.get(
    'https://firefly.example.com/api/v1/cron/d5ea6b5fb774618dd6ad6ba6e0a7f55c',
    headers={
        'X-Trace-Id': '40c71bbb-c676-4f24-83cf-cc725d7d7a00',
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)
```