Skip to main content
An agent profile holds everything a workflow needs to sign in and act as one identity. A profile carries:
  • credentials in a vault
  • two-factor secrets
  • cookies
  • browser cache and session state
  • proxy and captcha settings
  • an email inbox
A profile is reusable. Many workflows can share one profile, and one workflow can run with a different profile on every execution.

​
Attaching a profile to an execution

An execution uses at most one profile. You pick it when you start the execution.
Pass agentProfilePoolId instead to let Asteroid choose a profile from a pool.
agentProfileId and agentProfilePoolId are mutually exclusive. Pass one or the other, never both.
On the platform, choose the profile or the pool in the dropdown next to Run. See Call a workflow from your code for the full execute call.

​
Profile configuration

  • Proxy country code — the country the proxy routes through. One of us, uk, fr, it, jp, au, de, fi, ca.
  • Proxy type — the managed proxy connection to use. basic.
  • Persistent IP — keep the same IP address across requests.
Persistent IP locks the profile to a basic proxy in the us. The country and type selectors are fixed while it is on. It works with a platform-managed proxy only. Custom and gateway proxy modes reject it.
Turn automatic captcha solving on or off for the profile.
Cache persistence controls whether browser cache and cookies survive between runs.
  • On — the profile keeps session state, cookies and cached data across runs.
  • Off (the default) — every execution starts with a fresh browser state.
Clear the stored cache at any time with Clear Cache on the profile.
Every profile gets an inbox at {prefix}@agentmail.asteroid.ai. The default prefix is the profile’s UUID. Set a prefix to get a readable address. See Workflow emails.
Create and manage profiles on the platform, through the API, or through the SDKs. See the API reference.
Deleting a profile affects every workflow that references it. Check that no live automation depends on it first.

​
Credentials and 2FA

A profile stores credentials in a vault. It can also hold a TOTP secret, so a workflow generates its own authenticator codes. See Credentials & 2FA for how Asteroid stores, references, and keeps them out of the model.

​
Cookies

A profile can store site cookies, so an authenticated session survives between runs. Add cookies when you create the profile, or manage them later through the API. A cookie has these fields:

​
Profile pools

A profile pool groups profiles together. You point a run at the pool, and Asteroid picks a profile from it. Pools solve four problems:
  • Credential conflicts — stop two executions using one account at the same time.
  • Rate limits — spread requests across several accounts.
  • Availability — fall back to another profile when one is busy.
  • Manual selection — remove the choice from every execute call.

​
Selection strategies

A pool uses one of two strategies. Least recently used rotates fairly. With profiles A, B and C, an execution after B picks whichever of A or C idled longest. Most recently used concentrates work on fewer profiles. It keeps browser state and authenticated sessions warm.

​
Concurrent use

allowConcurrentUse decides whether a busy profile can be picked again.
With allowConcurrentUse: false, a request fails immediately when every profile in the pool is busy. The error says no profile is available. Add more profiles, allow concurrent use, or send "onCapacityLimit": "queue" on the execute call. The execution is then accepted as queued and starts when a profile frees. See Queue when capacity is full.

​
Pool constraints

An execute call takes agentProfileId or agentProfilePoolId, never both.
  • Every profile in a pool belongs to the same organization.
  • A pool name is unique within an organization.
  • A profile from another organization cannot join the pool.
  • A pool needs at least one profile before an execution can use it.
  • Remove the last profile and no new execution can use the pool.
Match the pool size to your parallelism. Five simultaneous runs need at least five profiles. Add one or two spare profiles for peak load.
A pool works with every profile feature — credentials, cookies, TOTP secrets, inbox and cache persistence. The selected profile’s configuration applies exactly as if you had named it yourself.

Call a workflow

Pass a profile or a pool on the execute call

Credentials & 2FA

How Asteroid stores and uses them

Workflow emails

The inbox each profile owns

Workflow settings

What the workflow owns instead of the profile

Security

How Asteroid protects stored credentials