Execute an ATRS Schedule Through the REST API

The ATRS REST API can execute an existing schedule without requiring a user to open ATRS and run it manually. An integration can submit the schedule for execution, monitor its progress, and determine whether processing completed successfully.

For complete request schemas and endpoint documentation, use the ATRS Developer Hub.

Before you begin

Ensure that:

The ATRS API service is installed and running.
The ATRS scheduler is running.
The schedule exists in ATRS and is correctly configured.
The reporting account used by the schedule can access the report.
The schedule has valid destinations and delivery credentials.
Your application has a valid access token.
You know the schedule’s unique ID and schedule type.

If the API service or API client has not been configured, see Manage the ATRS API Service and API Clients.

Choose an execution method

ATRS provides different execution methods for different integration requirements.

Asynchronous execution

Asynchronous execution submits the schedule and returns an execution ID while processing continues.

Use this method when an application needs to:

Submit work without keeping the original request open.
Monitor execution separately.
Track multiple concurrent requests.
Set a time limit for monitoring.
Attempt cancellation when necessary.

This is the preferred approach for most integrations.

Synchronous execution

Synchronous execution keeps the request open while ATRS runs the schedule.

Use this method only when the calling application can safely wait for processing to finish. Report rendering and delivery can take longer than a typical HTTP request.

Scheduled-time execution

Scheduled-time execution runs the schedule as though it had been started by the ATRS scheduler. This execution method can advance the schedule’s next-run information.

Use it only when the execution should affect the schedule’s normal scheduling cycle.

Immediate execution

Immediate execution starts a separate execution process for supported workflows. Use the API reference to confirm the required request and returned identifier for this execution method.

Identify the schedule

An execution request must identify the existing ATRS schedule.

Use the schedule’s:

Unique ID.
Schedule type.

The unique ID is the identifier assigned to the schedule by ATRS. Do not confuse it with an execution ID or operating-system process ID.

If your integration starts with a folder path and schedule name, use the appropriate public discovery operation to resolve the schedule’s unique ID before submitting the execution request.

Submit the schedule

Authenticate the request and submit the schedule using the execution method appropriate for the integration.

For an asynchronous request, ATRS returns an execution ID. Store this value immediately because it is used to monitor that specific execution.

A successful submission means ATRS accepted the execution request. It does not by itself confirm that the report was rendered or delivered successfully.

Monitor the execution

Use the returned execution ID to retrieve the execution status.

Commonly observed execution states include:

Waiting
Executing
Completed

Monitor the execution at a controlled interval and stop polling when:

ATRS reports a final status.
The integration’s monitoring deadline is reached.
The execution is cancelled or otherwise reconciled.

Do not repeatedly submit the same schedule because a status request is slow or temporarily unavailable. First check the existing execution ID and the API Execution Queue to avoid creating duplicate deliveries.

Confirm the result

When the execution reaches a final state:

Review the execution result.
Inspect any returned error information.
Confirm that the expected report was produced.
Verify delivery at the configured destination.
Review the applicable ATRS history or delivery records when further confirmation is required.

Execution completion and delivery confirmation are separate checks. A completed execution record does not necessarily prove that every destination received the expected output.

Cancelling an execution

ATRS provides an operation that attempts to cancel an asynchronous execution using its execution ID.

Cancellation is not guaranteed to reverse work that has already occurred. A report may already have been rendered, written to disk, or delivered before the cancellation request is processed.

After requesting cancellation, retrieve the execution status and inspect the destination before deciding whether to retry.

Use a controlled first execution

For the first execution through an integration:

Use an existing schedule that already runs successfully in ATRS.
Use a controlled report and destination.
Confirm the schedule’s unique ID and schedule type.
Monitor the execution through completion.
Verify the resulting output and delivery.
Record the execution ID with the integration’s activity log.

After confirming the workflow, apply it to production schedules and destinations.

Complete working example

For a complete PowerShell example, follow Authenticate, Execute, and Monitor a Schedule. The recipe obtains an access token, submits an existing schedule asynchronously, monitors its status with a time limit, and checks the reported execution result.