Semrush AIO Element Data
semrushAioElementDataFetch one Semrush Enterprise AIO report element (a table's rows, a non-table element's blocks, or a multiTable's child element IDs) using a verified account-bound browser profile.
Category: other•Timeout: 300s• Retryable
Input schema
POST this shape to /api/v1/tasks as the input field when creating a task in a group of type semrushAioElementData.
{
"type": "object",
"description": "Keys not declared here are accepted by the server and ignored by the executor (a 0.7.3 holder ignores every 1.1.0 input); from desktop 0.7.4 the output lists them in ignoredInputKeys. null for an optional input means not provided. maxItems and maxLength below are the executor's limits: the server does not check them, and the executor fails the task with Invalid <field> when one is exceeded.",
"properties": {
"accountRef": {
"type": "string",
"description": "Operator-chosen account slug; 1-64 letters, digits, dots, underscores or hyphens. Never a credential.",
"minLength": 1,
"maxLength": 64,
"pattern": "^[A-Za-z0-9._-]{1,64}$"
},
"workspaceId": {
"type": "string",
"description": "Semrush Enterprise workspace ID.",
"minLength": 1
},
"elementId": {
"type": "string",
"description": "Semrush Enterprise AIO report element ID. Table elements return rows; other element types return their blocks (desktop 0.7.4+; 0.7.3 accepts tables only).",
"minLength": 1
},
"pageId": {
"type": "string",
"description": "Optional report page ID, used only as source context; does not filter the data request."
},
"projectId": {
"type": "string",
"description": "Semrush AI project ID, sent as the data request's project_id. Omit for every project visible in the workspace. Desktop 0.7.4+; a 0.7.3 holder ignores it and returns the unfiltered table.",
"pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$"
},
"models": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 1024
},
"minItems": 1,
"maxItems": 100,
"description": "Engines to keep, matched exactly against CBF_model; several values are OR-ed. \"search-gpt\" is ChatGPT and \"google-ai-overview\" is Google AI Overview. Desktop 0.7.4+; a 0.7.3 holder ignores it and returns the unfiltered table."
},
"dateFrom": {
"type": "string",
"description": "First day to keep, YYYY-MM-DD (CBF_date__start gte). Desktop 0.7.4+; a 0.7.3 holder ignores it and returns the unfiltered table.",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$"
},
"dateTo": {
"type": "string",
"description": "Last day to keep, YYYY-MM-DD (CBF_date__end lte). Desktop 0.7.4+; a 0.7.3 holder ignores it and returns the unfiltered table.",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$"
},
"subreddits": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 1024
},
"minItems": 1,
"maxItems": 100,
"description": "Subreddits to keep, matched exactly against CBF_subreddit; several values are OR-ed. Desktop 0.7.4+; a 0.7.3 holder ignores it and returns the unfiltered table."
},
"tags": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 1024
},
"minItems": 1,
"maxItems": 100,
"description": "Prompt tags to keep, matched exactly against CBF_tags; several values are OR-ed. Desktop 0.7.4+; a 0.7.3 holder ignores it and returns the unfiltered table."
},
"promptContains": {
"type": "string",
"description": "Keep rows whose prompt contains this text (prompt contains). Desktop 0.7.4+; a 0.7.3 holder ignores it and returns the unfiltered table.",
"minLength": 1,
"maxLength": 1024
},
"advancedFilter": {
"type": "object",
"description": "A Semrush filter tree placed in filters.advanced alongside the typed filters above: a group {\"op\": \"and\"|\"or\", \"filters\": [...]} or a leaf {\"col\", \"op\", \"val\"}. Leaf ops: eq, neq, begins_with, not_begins_with, ends_with, not_ends_with, contains, not_contains, regexp_contains, url_match, lt, lte, gt, gte. val is a string or a finite number. At most 1024 nodes, depth at most 6, at most 16 KB serialized. Leaf col matches ^[A-Za-z_][A-Za-z0-9_.]{0,127}$ (the element's own advanced-filter keys). The executor rejects anything else. Desktop 0.7.4+; a 0.7.3 holder ignores it and returns the unfiltered table."
},
"sort": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"pattern": "^[A-Za-z_][A-Za-z0-9_]{0,63} (asc|desc)$"
},
"minItems": 1,
"maxItems": 16,
"description": "Server-side order, sent as pagination.sort_columns: each entry is \"<column> asc\" or \"<column> desc\", e.g. \"responses desc\". Desktop 0.7.4+; a 0.7.3 holder ignores it and returns the unfiltered table."
},
"linkIncludes": {
"type": "string",
"description": "Optional case-sensitive substring filter on each row’s link."
},
"fields": {
"type": "string",
"description": "Comma-separated fields to return, or \"*\" alone for every column the matched rows carry (desktop 0.7.4+; 0.7.3 fails the task with Invalid fields). \"*\" cannot be combined with names. Default: link,mentions,prompts,responses,subreddit, which are Top Threads' columns whatever the element, so on any other element omitting fields returns empty {} rows. A well-formed name the table does not have is not an error: no row carries it (a 0.7.6 holder lists it in the output's missingFields; on 0.7.4, compare fields with columns). Invalid fields fires only for a non-string, an empty list, a malformed name, or \"*\" mixed with names."
},
"excludeFields": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"pattern": "^[A-Za-z_][A-Za-z0-9_]{0,63}$"
},
"minItems": 1,
"maxItems": 100,
"description": "Fields to drop from the selection, e.g. [\"prompt_list\"] with fields \"*\". Desktop 0.7.4+; a 0.7.3 holder ignores it and returns the unfiltered table."
},
"maxInlineRows": {
"type": "integer",
"minimum": 1,
"maximum": 20000,
"default": 2000,
"description": "Maximum rows returned after filtering. Applied by the executor."
},
"rowOffset": {
"type": "integer",
"minimum": 0,
"maximum": 1000000,
"default": 0,
"description": "Matched rows to skip before the first returned row, for paging with nextRowOffset. Desktop 0.7.4+; a 0.7.3 holder ignores it and returns the first page again."
},
"maxPayloadBytes": {
"type": "integer",
"minimum": 65536,
"maximum": 16777216,
"default": 12582912,
"description": "UTF-8 byte budget shared by the returned rows and blocks: payloadBytes plus the bytes of blocks ({} for a plain table) stays within it. Rows past it are left for the next page (truncatedBy \"bytes\"). Every page that still has matched rows returns at least one; rowOffset at or past rowCount returns rows [] with nextRowOffset null. A single row over the budget, blocks alone over it, or rows and blocks together over it fail the task. Desktop 0.7.4+."
},
"includeConfig": {
"type": "boolean",
"default": false,
"enum": [
false,
true
],
"description": "Also return the element's config block, with account identifiers, request headers and trace IDs removed; null with configTruncated when over its size cap. Desktop 0.7.4+."
},
"clientRef": {
"type": "string",
"description": "Caller's own reference, echoed as clientRef in the output when it matches ^[A-Za-z0-9._:-]{1,120}$ and omitted otherwise; never fails the task. Desktop 0.7.4+.",
"pattern": "^[A-Za-z0-9._:-]{1,120}$"
},
"upstreamPage": {
"type": "object",
"properties": {
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 5000,
"default": 5000,
"description": "Rows Semrush returns for this page (pagination.limit). UPSTREAM_PAGE_MAX_LIMIT and UPSTREAM_PAGE_DEFAULT_LIMIT, both 5000 (kept after the 2026-09-27 sizing probe)."
},
"offset": {
"type": "integer",
"minimum": 0,
"maximum": 10000000,
"description": "Rows Semrush skips before this page (pagination.offset)."
}
},
"additionalProperties": false,
"description": "Page the table on Semrush's side: the data request carries pagination {limit, offset, sort_columns}. Requires a non-empty sort that ends in a unique key set for the element, or rows can repeat or go missing between pages; the README lists the sets. Missing or empty sort, any other key, or a value out of range fails the task with Invalid upstreamPage. rowOffset, maxInlineRows and maxPayloadBytes then apply within the upstream page, and tableRowCount counts that page's rows. Desktop 0.7.6+; an older holder ignores it and returns the whole table (0.7.4 lists it in ignoredInputKeys)."
}
},
"required": [
"accountRef",
"workspaceId",
"elementId"
]
}Output schema
Executors submit their output matching this shape to /api/v1/tasks/[taskId]/submit. Readers pull it back from task detail endpoints.
{
"type": "object",
"properties": {
"contractVersion": {
"type": "string",
"const": "1.1.0",
"description": "Present from desktop 0.7.4. Absent means the holder ignored every 1.1.0 input."
},
"executorVersion": {
"type": "string",
"description": "Version of the desktop build that ran the task."
},
"clientRef": {
"type": "string",
"description": "The input clientRef, when it was valid."
},
"element": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"type": {
"type": "string"
},
"title": {
"type": "string"
},
"workspaceId": {
"type": "string"
},
"pageId": {
"type": "string",
"description": "Omitted when the input had no pageId."
}
},
"required": [
"id",
"type",
"title"
]
},
"request": {
"type": "object",
"description": "The /data request body the executor actually sent: project_id, filters and pagination as applied. Compare it with the input before trusting a filtered result."
},
"fetchedAt": {
"type": "string",
"format": "date-time"
},
"window": {
"type": "string",
"enum": [
"all_time_unfiltered",
"filtered"
],
"description": "all_time_unfiltered when no projectId, model, date, subreddit, tag, prompt or advanced filter was applied; filtered otherwise."
},
"tableRowCount": {
"type": "integer",
"minimum": 0,
"description": "All rows received, before local filtering. With upstreamPage, the rows of that upstream page only."
},
"rowCount": {
"type": "integer",
"minimum": 0,
"description": "Rows matching linkIncludes, before the inline limit."
},
"rowOffset": {
"type": "integer",
"minimum": 0,
"description": "The input rowOffset this page starts at."
},
"nextRowOffset": {
"type": [
"integer",
"null"
],
"minimum": 0,
"description": "rowOffset for the next page, or null when this page reaches the last matched row."
},
"upstreamOffset": {
"type": "integer",
"minimum": 0,
"description": "With upstreamPage: the upstream offset this page starts at, echoed. Absent otherwise."
},
"upstreamNextOffset": {
"type": [
"integer",
"null"
],
"minimum": 0,
"description": "With upstreamPage: upstreamOffset plus limit when Semrush returned a full page, so there may be more; null when the page came back short and the table ends here. Absent otherwise."
},
"upstreamTotal": {
"type": "null",
"description": "With upstreamPage: always null, because Semrush returns no row total. Absent otherwise."
},
"fields": {
"type": "array",
"items": {
"type": "string"
}
},
"columns": {
"type": "array",
"items": {
"type": "string"
},
"description": "Every upstream column observed across the matched rows, before projection to fields (the full upstream set, not just fields), in first-seen order."
},
"columnTypes": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "Keyed by every column in columns (observed across the matched rows, before projection): the JSON type names seen in it (string, number, boolean, object, array, null), joined with \"|\" in first-seen order when there is more than one, e.g. \"string|null\"."
},
"rows": {
"type": "array",
"items": {
"type": "object"
}
},
"rowsTruncated": {
"type": "boolean",
"description": "Whether matched rows remain after this page; equals truncatedBy !== null."
},
"truncatedBy": {
"type": [
"string",
"null"
],
"enum": [
"rows",
"bytes",
null
],
"description": "What ended the page early: maxInlineRows (rows), maxPayloadBytes (bytes), or null."
},
"payloadBytes": {
"type": "integer",
"minimum": 0,
"description": "UTF-8 bytes of the serialized rows."
},
"config": {
"type": [
"object",
"null"
],
"description": "With includeConfig: the element's config block, scrubbed. Denied keys (account, user, token, header, trace and similar) keep their name with the value \"[stripped]\"; any string containing an email becomes \"[redacted]\" and an email-shaped key is dropped. null when upstream has no config or it is not an object, and when the scrubbed config exceeds 64 KiB or 32 levels of nesting."
},
"configTruncated": {
"type": "boolean",
"description": "With includeConfig: true only when config is null because it exceeded 64 KiB or 32 levels; false when it is returned, or null because upstream had none or it was not an object."
},
"topLevelKeys": {
"type": "array",
"items": {
"type": "string"
},
"description": "Top-level keys of the element response."
},
"blocks": {
"type": [
"object",
"null"
],
"description": "Every block of the element response except row data: for a table, the blocks around the rows (e.g. userVariables); a non-table element whose data is not row-shaped keeps data here. String values get the same email redaction as config (\"[redacted]\"). null only with blocksTruncated (desktop 0.7.6+)."
},
"blocksTruncated": {
"type": "boolean",
"const": true,
"description": "Present, and true, only when the blocks nest deeper than the executor's redaction depth cap; blocks is then null. Desktop 0.7.6+."
},
"missingFields": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"description": "Requested fields names that no matched row carries (a typo, or a column this element does not have), in request order. Present only when there is one and the matched rows have columns. Desktop 0.7.6+."
},
"children": {
"type": "array",
"items": {
"type": "string"
},
"description": "For a multiTable element, the child element IDs to fetch one by one."
},
"ignoredInputKeys": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[A-Za-z_][A-Za-z0-9_]{0,63}$"
},
"description": "Input keys this executor did not recognise and ignored. A key whose name does not match the pattern is ignored too but not echoed."
},
"timings": {
"type": "object",
"properties": {
"fetchMs": {
"type": "integer",
"minimum": 0,
"description": "Milliseconds the element data request took upstream."
}
},
"description": "Diagnostics from the run; more keys may appear."
}
},
"required": [
"element",
"fetchedAt",
"window",
"tableRowCount",
"rowCount",
"fields",
"rows",
"rowsTruncated"
]
}Ready to run Semrush AIO Element Data?
Create a project, approve an executor, and push your first semrushAioElementData task.