Sessions & Runs

Every time you run a project, RTILA X creates a Session. A session is a complete record of one execution: when it started, when it ended, whether it succeeded, and what data was produced. Sessions are your execution history — they let you track progress, debug failures, and resume interrupted runs.

---

What Is a Session?

A session represents one complete execution of a project. Think of it as a “run record” that tracks everything that happened during that execution.

Session Fields

Field	Type	Description
Project	Relation	The project that was executed
Scheduler	Relation	The scheduler that triggered this run (if scheduled)
Start Time	Date/Time	When the execution began
End Time	Date/Time	When the execution finished (empty if still running)
Status	Select	Current state: running, completed, failed, or stopped
Checkpoint	JSON	Progress data for resume capability
Created	Date/Time	When the session record was created

Session Statuses

Status	Meaning
running	The project is currently executing
completed	The project finished successfully
failed	The project encountered an error and stopped
stopped	The user manually stopped the execution

---

Viewing Runs

The Project Runs Page

1. Click Project Runs in the sidebar.
2. You’ll see a table of all your execution sessions.

Table Columns

Column	Description
Run Started	The date and time the run began. Includes a calendar icon for scheduled runs.
Run Duration	How long the run took (formatted as Xh Ym Zs)
Checkpoint Summary	A summary of checkpoint data (see below)
Status	The current status: running, completed, failed, or stopped
Actions	Buttons for Run Triggers, View Memory, Ask AI to Debug, and Delete

Scheduled vs. Manual Runs

Scheduled runs (triggered by the Task Scheduler) show a calendar icon next to the start time. Manual runs (started by clicking Run) don’t show this icon.

---

Filters

The Project Runs page has filters to help you find specific sessions:

Filter	Description
Project	Filter by project. Shows only runs for the selected project.
Start Date	Filter runs that started after this date.
End Date	Filter runs that started before this date.
Type	Filter by run type: All Types, Scheduled Runs, or Manual Runs.
Status	Filter by status: running, completed, failed, or stopped.

Using Filters

1. Select a project from the Project dropdown.
2. Optionally set a date range using the date pickers.
3. Choose a run type (All, Scheduled, or Manual).
4. Choose a status filter.
5. The table updates automatically.

Tip: Combine filters to find specific runs. For example: filter by project + “failed” status to see all failed runs for a specific project.

---

Session Actions

Each session row has action buttons:

Run Triggers

Manually trigger post-execution triggers for a completed or failed session.

1. Click the play icon (▶️) in the Actions column.
2. RTILA queues the project’s triggers for execution.
3. The triggers run as a separate relay job.

Note: This is useful when triggers failed during the original run, or when you want to re-send data to a destination.

View Memory

View the memory state (variables and data) captured during the run.

1. Click the brain icon (🧠) in the Actions column.
2. The Memory State modal opens.
3. You’ll see a table of key-value pairs.

Ask AI to Debug

Open an AI chat with the session’s logs for debugging help.

1. Click the bug icon (🐛) in the Actions column.
2. RTILA creates a new AI chat linked to the project.
3. The session’s logs are loaded into the chat context.
4. The AI analyzes the logs and suggests fixes.

Tip: This is especially useful for failed runs. The AI can identify what went wrong and suggest selector fixes or command adjustments.

Delete

Delete a session and all its associated data.

1. Click the trash icon (🗑️) in the Actions column.
2. A confirmation dialog appears.
3. Click Delete to confirm.

Warning: Deleting a session permanently removes:

• The session record
• All logs generated during the run
• All scraped data from that run

This action cannot be undone. You cannot delete a session that is currently running.

---

Checkpoint Summary

The Checkpoint Summary column shows a quick overview of the session’s checkpoint data:

Metric	Description
URLs Failed	Number of URLs that failed during the run
URLs Processed	Number of URLs successfully processed
State Variables	Number of runtime variables captured in the checkpoint
Memory Keys	Number of memory entries stored

Reading the Checkpoint Summary

Summary Shows	What It Means
URLs Failed: 0, URLs Processed: 10	All URLs were processed successfully
URLs Failed: 3, URLs Processed: 7	3 URLs failed, 7 succeeded
State Variables: 5	5 runtime variables were saved
Memory Keys: 2	2 memory entries were stored

---

Memory State

The Memory State shows all runtime variables and data that were active at the end of a run.

What’s in Memory

Key Type	Description
Runtime variables	Variables created by set_variable, get_text, etc.
Extracted data	Data stored in memory by extract_data
Loop state	Current iteration state for for_each loops
Custom data	Any data stored via execute_script

Viewing Memory

1. Click the brain icon on a session.
2. The modal shows a table with Key and Value columns.
3. Long values are truncated with [TRUNCATED...] markers.
4. Click Close to dismiss the modal.

Tip: Memory state is useful for debugging. If a variable has an unexpected value, you can see exactly what was stored during the run.

---

Checkpoints

Checkpoints are RTILA’s safety net. They save your progress during long-running automations so you can resume after interruptions.

How Checkpoints Work

During execution, RTILA periodically saves:

Data Saved	Purpose
Next URL Index	Which URL to process next
Variables	All current runtime variables
Memory	All memory entries
Failed URLs	List of URLs that failed (for retry)

When Checkpoints Are Saved

Checkpoints are saved:

• After each URL is processed
• After each command execution
• After variable changes
• After data extraction

When You Need Checkpoints

You’ll encounter the checkpoint dialog when:

• A run was interrupted (crash, network drop, manual stop)
• A previous run didn’t complete
• You want to retry failed URLs

The Checkpoint Dialog

When you try to run a project that has an incomplete previous run, RTILA shows a dialog:

Checkpoint Options

Option	What It Does	When to Use
Resume	Continue from where the run left off	The run was interrupted and you want to continue
Retry Failed	Re-run only the URLs that failed	Some URLs failed but most succeeded
Start New Run	Start completely fresh	You want to begin over from scratch

Resume

When you choose Resume:

• RTILA loads the checkpoint data.
• It starts from the Next URL Index (skipping already-processed URLs).
• All runtime variables are restored.
• Memory state is restored.
• The run continues as if it was never interrupted.

Retry Failed

When you choose Retry Failed:

• RTILA loads the list of Failed URLs from the checkpoint.
• It runs only those URLs.
• Successfully processed URLs are not re-run.
• Variables and memory from the previous run are restored.

Start New Run

When you choose Start New Run:

• All checkpoint data is discarded.
• The project runs from the beginning.
• No previous state is carried over.
• This is equivalent to running the project for the first time.

Important: If your checkpoint contains failed URLs and you choose “Start New Run,” those failed URLs are cleared. If you want to retry them later, choose “Retry Failed” instead.

---

Checkpoint Data Structure

For advanced users, here’s what’s stored in a checkpoint:

{
  "version": 1,
  "nextUrlIndex": 5,
  "variables": {
    "search_term": "web scraping",
    "page_count": 3,
    "last_price": "29.99"
  },
  "memory": {
    "_extractedHashes": { "dataset_name": ["hash1", "hash2"] }
  },
  "failedUrls": [
    "https://example.com/page/7",
    "https://example.com/page/12"
  ]
}

Field	Description
version	Checkpoint format version (always 1)
nextUrlIndex	The index of the next URL to process
variables	All runtime variables at the time of saving
memory	Memory entries (includes deduplication hashes)
failedUrls	URLs that failed during the run

---

Checkpoint Storage

Checkpoints are stored in two places depending on your setup:

Mode	Storage Location
API Mode (connected to database)	Stored in the session’s checkpoint field in the database
File Mode (standalone)	Stored as a JSON file in ~/.rtila-x/checkpoints/

File-Based Checkpoints

In file mode, checkpoints are saved to:

~/.rtila-x/checkpoints/{project_name}.json

These files are automatically deleted when a run completes successfully.

---

Tips and Best Practices

Tip	Why It Matters
Monitor running sessions	Check the Project Runs page for active runs
Use Retry Failed for partial failures	Don’t re-run everything if only a few URLs failed
Check Memory State for debugging	See exactly what variables were set during a run
Use Ask AI to Debug for failures	The AI can analyze logs and suggest fixes
Don’t delete sessions you might need	Session data includes logs and scraped data
Use filters to find specific runs	Filter by project + status to narrow results
Check Checkpoint Summary before resuming	See how many URLs succeeded vs. failed
Start New Run for fresh data	Use when you want clean data without previous state
Scheduled runs show a calendar icon	Easy to distinguish from manual runs
Long-running projects benefit from checkpoints	If your project processes many URLs, checkpoints save progress