Dedicated Instances

• A portal is slow or rate‑limited to log into, and you run many tasks against it.
• You get bursts of work for the same login (e.g. 30 requests three times a day).
• You want to control the order/concurrency in which a portal’s tasks run.

​

Quick start

curl -X POST https://inference-api.optexity.com/api/v1/inference \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_OPTEXITY_API_KEY" \
  -d '{
    "endpoint_name": "your_portal_endpoint",
    "input_parameters": { "username": ["alice@example.com"] },
    "unique_parameter_names": ["username"],
    "is_dedicated": true,
    "max_parallelism": 1,
    "per_login_parallelism": 1
  }'

curl -X POST https://inference-api.optexity.com/api/v1/inference \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_OPTEXITY_API_KEY" \
  -d '{
    "endpoint_name": "your_portal_endpoint",
    "input_parameters": { "username": ["alice@example.com"] },
    "unique_parameter_names": ["username"],
    "is_dedicated": true
  }'

​

Request fields

​

How it works

• A “login” is a value of your unique parameters. Whatever you list in unique_parameter_names becomes the identity of a login (and its queue). With unique_parameter_names: ["username"], each distinct username is its own login.
• per_login_parallelism controls how many warm containers one login may spread its tasks across. With the default 1, a login uses a single warm container and its tasks run one at a time on it.
• max_parallelism is the portal‑wide ceiling on warm containers across all logins.
• Idle reaping. A warm container that has had no work for a few minutes is shut down and its capacity returns to the shared pool. The next task for that login starts a fresh container (which logs in again). Smaller idle windows reclaim capacity faster; larger ones re‑login less often.
• Queue‑and‑return. If there’s no free capacity when your request arrives, the request is accepted and queued (not rejected, not blocked). It runs as soon as capacity frees up. Requests for a given login‑queue are served in priority order (lower number runs first; omitted priority runs last). Tasks with the same priority run first‑in, first‑out.

​

Examples

​

One login, a burst of tasks

{
  "endpoint_name": "billing_portal",
  "input_parameters": { "username": ["acme@example.com"] },
  "unique_parameter_names": ["username"],
  "is_dedicated": true
}

{
  "endpoint_name": "billing_portal",
  "input_parameters": { "username": ["acme@example.com"] },
  "unique_parameter_names": ["username"],
  "is_dedicated": true,
  "max_parallelism": 3,
  "per_login_parallelism": 3
}

​

Multiple unique logins, isolated

{
  "endpoint_name": "billing_portal",
  "input_parameters": { "username": ["acme@example.com"] },
  "unique_parameter_names": ["username"],
  "is_dedicated": true,
  "max_parallelism": 5
}

​

More logins than capacity

• The first 4 logins each get a warm container and start immediately.
• The 5th request is accepted and queued (status queued). It is not an error.
• It runs as soon as a container frees up — for example when one of the first 4 logins sits idle long enough to be reclaimed, returning a slot to the pool.

​

Controlling the queue

• One queue per login (default isolation). Mark the login parameter as unique. Each login gets its own warm, logged‑in container.
  { "unique_parameter_names": ["username"] }
  
• One shared queue for the whole portal. Send no unique parameters ("unique_parameter_names": []). Every request funnels into a single warm container group and runs serialized — useful when a portal must never run two sessions at once.
  { "unique_parameter_names": [] }
  
• Custom grouping (different logins on one queue). Designate a dedicated routing parameter (say queue_key) in the automation and give the requests you want serialized together the same queue_key value — regardless of which login they use:
  {
    "endpoint_name": "billing_portal",
    "input_parameters": {
      "username": ["acme@example.com"],
      "queue_key": ["batch-1"]
    },
    "unique_parameter_names": ["queue_key"],
    "is_dedicated": true
  }
  
  Send another request with username: ["beta@example.com"] but the same queue_key: ["batch-1"], and both share one queue / container and run one at a time. Use a different queue_key value to put work on a separate queue.

​

Task priority

curl -X POST https://inference-api.optexity.com/api/v1/inference \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_OPTEXITY_API_KEY" \
  -d '{
    "endpoint_name": "billing_portal",
    "input_parameters": { "username": ["alice@example.com"] },
    "unique_parameter_names": ["username"],
    "is_dedicated": true,
    "priority": -1
  }'

• No preemption. A currently‑running task is never interrupted; priority only reorders waiting tasks.
• Scope is per login‑queue. A high‑priority task can only jump ahead of tasks in its own login‑queue — it never affects other users or other portals.
• Restart preserves priority. Restarting a task re‑queues it with its original priority.

​

Things to take special care of

• Every run still navigates to the automation’s url, even on a warm container. If your portal breaks when its page is reloaded, set reuse_page_if_already_on_url on the automation to start on the existing page instead. It applies to dedicated runs only.
• unique_parameter_names must be a subset of input_parameters. Names not present in your input_parameters are rejected.
• max_parallelism above the portal’s real capacity is unreachable — the surplus requests queue rather than running concurrently.
• Request limits are bounded server‑side. A request‑supplied max_parallelism is clamped to a platform maximum. An admin‑configured portal (see below) is not clamped.
• Limits are fixed per active portal. The first request that opens a portal’s reservation sets its max_parallelism / per_login_parallelism; later requests reuse those values until the portal goes fully idle and is reclaimed, after which a new burst can specify fresh limits.
• use_proxy cannot be combined with is_dedicated. A request with both set is rejected.
• Admin configuration takes precedence. If a portal is configured as dedicated on the Optexity side for your account, it runs dedicated with those limits even if your request sends "is_dedicated": false — you can opt in per request, but you cannot opt out of a portal that is configured dedicated.

​

FAQ