Intuned in depth

Introduction

Looking for a quick overview? Check out How Intuned works for the short version.

Intuned is a platform that enables developers to build and consume browser automations as code. Turn complex browser interactions into reliable, scalable APIs. Intuned allows you to:

Organize your automations into projects
Develop these automations as APIs
Deploy them effortlessly with no setup required
Execute them reliably on demand or at a schedule at any scale
Monitor their execution
Automate the hard parts with Intuned Agent—an async agent that builds and maintains browser automations for you

Projects

A Project is both your automation code and your runtime environment. A project usually represents a browser automation with a specific goal, such as:

A single website scraper
An integration with a platform

As code

A Project contains your browser automation APIs and shared logic—written in Python or TypeScript using Playwright.

Project/
├── apis/
│   ├── scrape-product.ts    # Your automation APIs
│   └── submit-form.ts
├── helpers/                  # Shared utilities
└── Intuned.json              # Project configuration

Each API is a function that receives a browser page and parameters, performs actions, and returns results. You have full control over the code—use any library, pattern, or approach that fits your needs.

At runtime

A Project is where everything comes together: Run records, Jobs, JobRuns, browser traces, logs, and AuthSessions all live within the Project that owns them. When you execute an API in a project, it produces a Run record associated with that project. The same applies to Jobs. See Execute for details.

Develop

There are multiple ways to develop your projects:

Online IDE: A web-based development environment accessible from your browser with a rich set of tools to help you build browser automations. Learn more about the Online IDE.
Locally: Use the CLI to develop your projects using your favorite IDE and tools. See Local development (CLI) for details.

A project’s code is divided into APIs that fall under the apis directory in your project’s code, with file system based routing. Each API is a function that accepts a browser page (via Playwright), takes parameters to customize the execution, and returns results.

apis/
  ├── scrape-product-list.ts
  ├── scrape-product-details.ts
  ├── order-product.ts
  └── ...

If you don’t want to develop the code yourself, see Intuned Agent.

Deploy

When you deploy a project, the code, dependencies, and configurations are built, packaged, and deployed on dedicated virtual machines.

Deployment model

Intuned uses different deployment strategies for Standalone Runs and Jobs to optimize for their distinct execution patterns.

Standalone APIs

To enable Standalone API access, you must enable API access at the project level via Intuned.json. Once enabled, Intuned deploys a pool of machines dedicated to handling your Standalone Run requests. The number of machines in this pool is controlled by the Max Concurrent Requests setting in your project’s replication settings. Each machine handles one request at a time—this ensures full isolation and consistent performance for each Run. When more requests arrive than there are available machines:

Incoming requests are queued
As machines complete their current Run, they pull the next request from the queue
Requests are processed in order

This model provides predictable scaling: if you set Max Concurrent Requests to 5, you’ll have 5 machines ready to process Runs concurrently.

Jobs (JobRuns)

Jobs use a different deployment model optimized for batch execution. Instead of a persistent pool, each JobRun provisions its own dedicated machines based on the job configuration’s machineCount setting. When a JobRun starts:

Intuned provisions the specified number of machines for that JobRun
The Runs within the JobRun are distributed across these machines
Once the JobRun completes, the machines are removed

This approach ensures Jobs get dedicated resources for their execution without affecting the Standalone API pool, and allows you to scale each JobRun independently based on its workload.

Execute

Once your project is deployed, you can start executing the APIs you developed.

Runs and Attempts

Every execution creates records that track what happened.

Run

A Run represents the logical execution of a single API. Each Run has one or more Attempts. A Run takes as input:

API name that you want to execute.
Parameters that you provide. These parameters are passed to the API function to customize its execution.
Configuration options like attempt limits, timeouts, authentication, and proxy settings

Once you trigger a Run, it enters a pending state while waiting to be picked up for execution. When picked up, it changes to started and remains there until execution completes, then transitions to success or failed. While pending or started, a Run may be canceled manually or automatically if pre-execution dependencies fail (e.g., authentication failure). Each Run produces either:

Result data returned by the API if the Run is successful
Error information if the Run fails or is canceled.

Attempt

An Attempt is the actual execution of the API code. While a Run is the logical execution, an Attempt is where the code actually runs. A Run always has at least one Attempt. If an Attempt fails, the Run creates a new Attempt (a retry) until the API succeeds or the maximum number of Attempts is reached. Each Run has at most one successful Attempt. Before an Attempt runs, it may trigger dependency Runs, such as authentication validation. If these pre-execution dependencies fail, the Attempt will be canceled, causing its Run to also be canceled. Each Attempt produces its own:

Result data returned by the API if the Attempt is successful.
Error information if the Attempt fails or is canceled.
Playwright Traces that show a detailed trace of the browser interactions during the Attempt execution, which can be useful for debugging and monitoring.
Logs that provide insights into the Attempt execution flow, useful for debugging and monitoring.

The result or error of a Run is the result or error of its last Attempt. This architecture provides fine-grained control and visibility while logically grouping related API executions, so you can manage and trace complex automation workflows.

Ways to trigger executions

There are two ways to trigger API executions: standalone Runs for on-demand execution, and Jobs for batch or scheduled execution.

Standalone Runs (single executions)

Standalone Runs allow you to execute a single API on demand. A standalone Run allows you to configure:

Single API and its parameters
Run configurations like attempt limits, timeouts, authentication, and proxy settings
Optional sink to send results to (e.g., webhook, blob storage, etc…)

Single Runs are perfect for:

On-demand executions (e.g., RPA tasks)
Testing and debugging

See Runs (single executions) for details.

Jobs (batched executions)

Jobs are a way to trigger or schedule multiple correlated Runs, track their progress, and monitor their results together. Jobs allow you to configure:

Multiple APIs, each with its own parameters.
Run configurations like attempt limits, timeouts, authentication, and proxy settings that apply to all Runs.
Concurrency settings to control how many Runs can execute in parallel.
Optional scheduling options (e.g., run every hour, daily, etc.)
Optional sink to send results to (e.g., webhook, blob storage, etc…)

Jobs are blueprints that define how multiple APIs execute together. Once executed, a Job creates a JobRun—a collection of Runs triggered as part of that execution. Jobs also support nested scheduling, where one API can dynamically expand the JobRun’s workload. For more details, check out the nested scheduling section. Jobs are perfect for:

Running multiple APIs in bulk and aggregating their results (e.g., web scraping)
Running automations on a schedule

See Jobs (batched execution) for details.

Nested scheduling

Nested scheduling is a feature that allows APIs that are running as part of a JobRun to extend their execution with other APIs. When an API is executed successfully, the APIs it extends will also be executed as part of the same JobRun. An API can extend the JobRun’s payload using the extend payload function part of Intuned’s Runtime SDK. Common use case: dynamic scraping Let’s say you’re scraping an e-commerce site where the product pages change frequently, and you don’t know all the product pages you need to scrape in advance. You can use nested scheduling to handle this dynamic workload:

Initial API: finds all product pages that need to be scraped
Uses extendPayload to expand the payload of the JobRun
Extended APIs: Runs and extracts each product details from product pages

This pattern is essential when the automation payload can change across JobRuns.

Example flow

Monitor

Every Run and Attempt produces detailed records you can inspect—statuses, results, logs, and browser traces to help you debug and optimize your automations. Each Run record includes:

Current status (Pending, Started, Success, Failed, Canceled)
Start and end timestamps
Parameters and configuration used
Result data if successful
Error information if failed or canceled
Link to Job and JobRun (if applicable)
Link to AuthSession (if applicable)
Attempts associated with the Run.
Links to pre-execution dependency runs (if applicable)

Each Attempt record includes:

Start and end timestamps
Parameters and configuration used
Result data if successful
Error information if failed or canceled
Playwright Trace link for detailed browser interaction trace
Logs for debugging and monitoring

You can view these records from the Runs section in your project on the Intuned Dashboard. If you’re using Jobs, each JobRun creates a record that includes:

Current status (In Progress, Completed, Failed)
Start and end timestamps
List of Runs associated with the JobRun

You can view these records from the Jobs section in your project on the Intuned Dashboard. See Monitoring and traces for details.

AuthSessions

Many browser automations require login to access content or perform actions:

Automating internal tools
Interacting with applications that have no APIs
Automating back-office workflows on behalf of users
Scraping user-specific data

Authentication can often be tricky to handle, especially when running at scale. When should I log in and when should I reuse existing sessions? How do I know that my session is still valid? What if I’m being logged out frequently? AuthSessions are Intuned’s answer to these challenges: a set of features to streamline authentication in browser automation.

How to use AuthSessions

Once you enable AuthSessions for your project (authed project):

All Runs will require an AuthSession to be executed.
Before each Attempt, the AuthSession will be validated and recreated if needed.
AuthSession creation and validation is defined in code.
- auth-sessions/check and auth-sessions/create APIs in your project.

This ensures every API runs with a valid session and keeps authentication consistent across all project APIs. When you trigger a Run for an Authed Project, you must provide an AuthSession as part of the Run configuration. You can use different AuthSessions for different Runs, allowing you to run automations on behalf of different users, and reuse AuthSessions across multiple Runs.

AuthSession usage patterns

Single account automation:
- Example: Company admin dashboard. Create one AuthSession to scrape analytics data, export reports, and update settings—each as its own API. All API executions can share the same AuthSession.
- Example: Authenticated data scraper. Create one AuthSession to log into a website and scrape available data.
Multi-account automation: User-specific integrations.
- Example: Social media manager tool. Create multiple AuthSessions (one per user when they “connect”) and run posting/scheduling APIs on behalf of each user. User A has AuthSession A, User B has AuthSession B.

AuthSession Runs

AuthSessions come with special types of Runs that encapsulate authentication operations. Unlike regular API Runs, these can combine different API Attempts in a single Run:

`AuthSession:Validate`

Triggered before each authed project API Attempt.
Its goal is to ensure a valid AuthSession is ready for the API Attempt to execute. More on this in the next section.
Starts with one or more check Attempts that run the check API.
If validation fails and auto recreation is enabled (which is true by default), it will execute create Attempts to recreate the AuthSession, and then reexecute check Attempts to re-validate it.

`AuthSession:Create`

Triggered when you manually create an AuthSession via dashboard or API.
Starts with one or more create Attempts to capture the browser state then check Attempts to validate it.

`AuthSession:Update`

Triggered when you manually update an existing AuthSession via dashboard or API.
Starts with one or more create Attempts to recreate the AuthSession then check Attempts to validate it.

How AuthSessions work

In authed projects, each Attempt execution will first validate the provided AuthSession by running a dependency Run (AuthSession:Validate), which ensures your API code never runs with an invalid session. If the AuthSession:Validate fails, the Attempt is canceled, which in turn cancels the entire Run without retrying. This is different from failed Attempts due to API execution errors, which will retry until the maximum number of Attempts is reached. AuthSession:Validate also supports auto recreation, which is enabled by default. When enabled, if the AuthSession check fails, Intuned will automatically attempt to recreate the AuthSession (by running the create code), and then re-validate it. If the recreation and re-validation succeed, the Attempt continues to execute the API. If either the recreation or re-validation fails, the validation run is considered failed and the Attempt is canceled. Key takeaways:

Every Attempt validates the AuthSession before execution by triggering an AuthSession validation Run as a pre-execution dependency.
Failed validation cancels the Attempt and therefore the Run.
Auto recreation can be controlled per-Run.

AuthSession types

Intuned supports three patterns for creating and managing AuthSessions:

Type	Who authenticates	Auto-recreation	Credentials stored	Best for
Credentials-based	Code	✓	By Intuned	Standard login flows
Runtime-based	Code	Required	Not stored	Changing credentials (OTPs, temp tokens)
Recorder-based	Human	✗	—	Complex login (MFA, CAPTCHA, biometrics)

Credentials-based AuthSessions use stored credentials to log in and create sessions. You create an AuthSession instance via dashboard or API, and Intuned triggers an AuthSession:Create Run that creates and validates the AuthSession (using the create and check APIs) with the provided credentials, then captures the browser state after completion. The credentials are stored securely by Intuned and used for recreation when the browser state expires or becomes invalid. This approach is suitable for programmatic login flows (e.g., username/password, API keys). To use this AuthSession, you provide its ID in the Run configuration.

{
  "api": "scrape-dashboard",
  "parameters": { /* ... */ },
  "authSession": {
    "id": "auth-session-1"
  }
}

When you trigger an authed API Run, Intuned reads the stored browser state and validates it before the API Attempt execution. If validation fails and auto recreate is enabled, Intuned will read the stored credentials, run the create API to recreate the session, and then re-validate it before proceeding with the Attempt execution. This all happens as part of the AuthSession:Validate run as mentioned above.

Figure: Attempt flow with credentials-based AuthSession

Runtime-based AuthSessions are created when you provide credentials as part of the Standalone Run API request—not as a separate AuthSession:Create Run from the dashboard or API. Runtime-based AuthSessions always have auto recreation enabled. This approach is suitable when credentials change frequently or cannot be stored (e.g., OTPs, temporary tokens). To use this AuthSession, you provide its ID and credentials in the Run configuration. If an ID is not provided, each Run will create a brand new AuthSession.

{
  "api": "scrape-dashboard",
  "parameters": { /* ... */ },
  "authSession": {
    "id": "auth-session-1",
    "runtimeInput": { /* ... */}
  }
}

When you trigger a run, before Attempt execution, if an AuthSession ID is provided and it exists, Intuned reads the stored browser state to validate against it. Otherwise, Intuned validates against an empty state. If validation fails, Intuned will use the passed credentials to run the create API to recreate the AuthSession, and then re-validate it before proceeding with the API Attempt execution.

Figure: Attempt flow with runtime-based AuthSession

Recorder-based AuthSessions allow you (or your users) to manually log in to a website using a browser recorder tool (hosted cloud-based browser). You perform the login steps in a real browser, and the recorder captures the browser state after a successful login. This captured state is then used for subsequent Runs.

If you need more information about how recorder-based AuthSessions work and how to enable and use them, contact support via Slack channel or email.

AuthSessions with Jobs

Jobs fully support AuthSessions. When you configure a Job for an authed Project, you specify the AuthSession in the job configuration. Each Run triggered as part of the JobRun will use the specified AuthSession, including extended Runs (via extendPayload nested scheduling). Auto recreation is configured at the Job level. Jobs have special handling for AuthSessions to ensure efficient execution at scale:

When a JobRun starts, it first validates the AuthSession by triggering an AuthSession:Validate Run, which can recreate the AuthSession if needed.
If the AuthSession:Validate Run fails, the JobRun is canceled.
Each Run in the JobRun will also validate the AuthSession before each Attempt execution.
If any AuthSession:Validate fails and recreation attempts fail, the JobRun pauses. You can then manually recreate the AuthSession via dashboard or API, and then resume the JobRun.

Each Attempt in the JobRun executes AuthSession:Validate with auto recreation disabled. If validation fails, the Attempt and Run are canceled. The JobRun then reruns AuthSession:Validate with auto-recreate enabled (the JobRun controls recreation, not individual Attempts). If this succeeds, the JobRun reschedules the canceled Runs with the new AuthSession state. This ensures efficiency, reliability, and prevents race conditions.

Figure: JobRun flow with AuthSessions

auto-recreate=true (default)
auto-recreate=false

Proxy support

You can configure a proxy to use with AuthSessions. When set, all runs using that AuthSession (Create, Update, Validate, and API Runs) use the specified proxy for browser interactions. This ensures all authentication and API executions route through the desired proxy. To change the proxy, update the AuthSession configuration.

Key features

Proxies

Websites may block traffic based on IP addresses, especially if they detect a high volume of requests from a single IP. Intuned allows you to configure proxies on Runs, enabling you to route your traffic through different IP addresses and avoid IP-based blocking. See Proxies for details.

Stealth mode

Automation libraries like Playwright often leave detectable fingerprints that websites can use to identify and block automated traffic. Intuned’s stealth mode helps your automations avoid detection by masking these fingerprints, making your browser interactions appear more like those of a real user. This can help in most bot-detection scenarios. See Stealth mode for details.

CAPTCHA solving

Some websites use advanced anti-bot measures, such as CAPTCHAs, to verify that a user is human. Intuned provides built-in support for solving CAPTCHAs encountered during browser automation, allowing your automations to continue running smoothly even when faced with these challenges. The CAPTCHA solver requires a headful browser. See CAPTCHA solving for details.

Intuned Agent

Intuned Agent is an async AI coding agent that takes some the hard work out of building and maintaining scrapers. It can help you:

Generate web scraper projects from scratch.
Update existing automations to add new features.
Fix automations based on failing Runs.

See Intuned Agent for details.

Observability

Intuned provides full observability into every Run, Attempt, and JobRun, giving you complete visibility into what happened and why. Each execution generates detailed logs, browser traces, and session recordings that help you debug issues, optimize performance, and understand your automation’s behavior. These tools make it easy to diagnose failures, verify that your automations are working correctly, and identify areas for improvement. See Observability for details.

What’s next?

Intuned vs. Others — How does Intuned compare to other tools and platforms
Playwright for Automation — Deep dive into Playwright and how to use it for browser automation

Getting started

Learn

Features

How-To

Integrations

References

Resources

​Introduction

​Projects

​As code

​At runtime

​Develop

​Deploy

​Deployment model

​Standalone APIs

​Jobs (JobRuns)

​Execute

​Runs and Attempts

​Run

​Attempt

​Ways to trigger executions

​Standalone Runs (single executions)

​Jobs (batched executions)

​Nested scheduling

​Monitor

​AuthSessions

​How to use AuthSessions

​AuthSession usage patterns

​AuthSession Runs

​AuthSession:Validate

​AuthSession:Create

​AuthSession:Update

​How AuthSessions work

​AuthSession types

​AuthSessions with Jobs

​Proxy support

​Key features

​Proxies

​Stealth mode

​CAPTCHA solving

​Intuned Agent

​Observability

​What’s next?

Introduction

Projects

As code

At runtime

Develop

Deploy

Deployment model

Standalone APIs

Jobs (JobRuns)

Execute

Runs and Attempts

Run

Attempt

Ways to trigger executions

Standalone Runs (single executions)

Jobs (batched executions)

Nested scheduling

Monitor

AuthSessions

How to use AuthSessions

AuthSession usage patterns

AuthSession Runs

`AuthSession:Validate`

`AuthSession:Create`

`AuthSession:Update`

How AuthSessions work

AuthSession types

AuthSessions with Jobs

Proxy support

Key features

Proxies

Stealth mode

CAPTCHA solving

Intuned Agent

Observability

What’s next?