Input schema (JSON)
{
"type": "object",
"required": [
"url"
],
"properties": {
"url": {
"type": "string",
"description": "The website's URL."
},
"name": {
"type": [
"string",
"null"
],
"description": "User-chosen name; null clears it."
},
"labels": {
"type": "array",
"items": {
"type": "integer"
},
"description": "IDs of labels to assign."
},
"limits": {
"type": "object",
"properties": {
"daily": {
"type": [
"integer",
"null"
],
"maximum": 10000,
"minimum": 1,
"description": "Max visits per day; null means no limit."
},
"total": {
"type": [
"integer",
"null"
],
"maximum": 500000,
"minimum": 1,
"description": "Max visits in total (lifetime); null means no limit."
},
"hourly": {
"type": "integer",
"maximum": 500,
"minimum": 1,
"description": "Max visits per hour — always at least 1 (an hourly cap is mandatory)."
}
},
"description": "Visit caps; null means no limit."
},
"paused": {
"type": "boolean",
"description": "Pause or resume visit delivery."
},
"actions": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"type",
"ratio"
],
"properties": {
"type": {
"enum": [
"click",
"click_rss",
"click_sitemap",
"scroll",
"refresh"
],
"type": "string",
"description": "What the app does — click a link, click an RSS or sitemap link, scroll, or refresh."
},
"ratio": {
"type": "integer",
"maximum": 100,
"minimum": 0,
"description": "Percentage of visits that perform this action (default 100 = every visit)."
},
"element": {
"type": "object",
"properties": {
"type": {
"enum": [
"any",
"internal_link",
"external_link",
"link",
"button",
null
],
"type": [
"string",
"null"
],
"description": "What to click: any element, a same-domain link (`internal_link`), an off-domain link (`external_link`), any link (`link`), or a button.\n"
},
"selection": {
"enum": [
"random",
"first",
"last",
null
],
"type": [
"string",
"null"
],
"description": "Which element to click when several match."
},
"url_filter": {
"type": [
"string",
"null"
],
"description": "Only click links whose URL contains this text; ignored when the element type is `button`."
},
"text_filter": {
"type": [
"string",
"null"
],
"description": "Only click elements whose visible text contains this."
}
},
"description": "Present for click-type actions."
}
},
"description": "A site action to apply. Same shape as SiteAction, but type and ratio are required."
},
"description": "The actions to perform."
},
"window": {
"enum": [
"latest",
"first"
],
"type": "string",
"description": "Which opened browser window the actions target — the most recent (latest) or the first (first)."
}
},
"description": "Auto-actions performed during visits."
},
"cookies": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"value"
],
"properties": {
"name": {
"type": "string",
"maxLength": 256,
"description": "Cookie name."
},
"value": {
"type": "string",
"maxLength": 256,
"description": "Cookie value."
},
"domain": {
"type": [
"string",
"null"
],
"maxLength": 256,
"description": "Domain to set the cookie on (a leading dot is dropped; subdomains are covered either way); null sets it on the visited site's host."
}
},
"description": "A cookie set on the browser session before the visit begins."
},
"maxItems": 10,
"description": "Cookies to set before each visit; replaces the stored list."
},
"devices": {
"type": "object",
"properties": {
"mobile": {
"type": "integer",
"maximum": 100,
"minimum": 0,
"description": "Percentage of visits sent to mobile devices."
},
"tablet": {
"type": "integer",
"maximum": 100,
"minimum": 0,
"description": "Percentage of visits sent to tablet devices."
},
"desktop": {
"type": "integer",
"maximum": 100,
"minimum": 0,
"description": "Percentage of visits sent to desktop devices."
}
},
"description": "Device targeting split, as percentages summing to 100."
},
"browsing": {
"type": "object",
"properties": {
"max_sub_windows": {
"type": "integer",
"maximum": 1,
"minimum": 0,
"description": "How many pop-up windows the visited site may open during a visit."
}
},
"description": "Browsing options."
},
"schedule": {
"type": "object",
"properties": {
"time_zone": {
"type": [
"string",
"null"
],
"description": "IANA time zone for the active-hours schedule (e.g. \"Europe/Paris\"); null uses your account timezone."
},
"active_hours_mask": {
"type": [
"string",
"null"
],
"description": "A weekly on/off schedule: a 168-character string, one character per hour (24 hours × 7 days). Each is `1` (active that hour) or `0` (paused). The first character is Monday 00:00 and each next is the following hour, ending Sunday 23:00, in `time_zone`. `null` or all-`1`s means always on; at least one hour must be active, so an all-`0`s mask is rejected.\n"
}
},
"description": "Active-hours scheduling."
},
"template_id": {
"type": "integer",
"format": "int64",
"description": "A site template to apply as the base configuration. Must be one of your own templates; an unknown id returns 422. The template's settings become the defaults; any field you also send in this request overrides the template's value for that whole field (shallow merge, per top-level field).\n"
},
"visit_duration": {
"type": "object",
"properties": {
"max_seconds": {
"type": "integer",
"maximum": 600,
"minimum": 10,
"description": "Longest visit duration, in seconds."
},
"min_seconds": {
"type": "integer",
"maximum": 600,
"minimum": 10,
"description": "Shortest visit duration, in seconds."
}
},
"description": "Visit duration range, in seconds."
},
"blocked_domains": {
"type": "object",
"properties": {
"rate": {
"type": "integer",
"maximum": 100,
"minimum": 0,
"description": "Percentage of visits to which domain blocking applies."
},
"domains": {
"type": "array",
"items": {
"type": "string"
},
"description": "Hostnames to block (e.g. `ads.example.com`; no scheme or path), one per entry. Up to 10."
}
},
"description": "Domains blocked during visits."
},
"traffic_quality": {
"type": "object",
"properties": {
"ipv6": {
"type": "boolean",
"description": "Whether IPv6 visitors may deliver visits to this site."
},
"low_quality_ips": {
"type": "boolean",
"description": "Whether low-quality IPs (VPN/proxy/datacenter) may deliver visits to this site."
}
},
"description": "Traffic quality controls."
},
"traffic_sources": {
"type": "array",
"items": {
"type": "integer"
},
"description": "IDs of traffic sources to assign; an empty list assigns the default \"Direct visits\" source."
},
"location_targeting": {
"type": "object",
"properties": {
"mode": {
"enum": [
"include",
"exclude"
],
"type": "string",
"description": "Whether the locations list is an allow-list (include) or a block-list (exclude)."
},
"locations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "ISO country code (alpha-2) or continent code, per type."
},
"type": {
"enum": [
"country",
"continent"
],
"type": "string",
"description": "Whether code is a country or a continent."
}
}
},
"description": "The countries/continents to include or exclude."
}
},
"description": "Country/continent targeting."
},
"visit_distribution": {
"enum": [
"even",
"asap"
],
"type": "string",
"description": "How visits are paced — \"even\" spreads them across the day, \"asap\" delivers as fast as possible."
}
}
}