Skip to content

List Comment Automations API

The List Comment Automations API returns existing comment automations so a client can inspect how each automation is scoped, what triggers it, what actions it performs, and how it has performed. Call GET {{API_BASE_URL}}/v1/comment-automations/ with an x-access-key header and, when you want to narrow the result, an accountId query parameter. The response contains an automations array; each entry combines identity fields with trigger, actions, and stats objects that should be read together rather than in isolation.

Request: GET {{API_BASE_URL}}/v1/comment-automations/

Use this endpoint when a dashboard, script, or agent needs an inventory of comment automations before deciding whether to create, update, or delete one. The request is a GET to {{API_BASE_URL}}/v1/comment-automations/ and the only query parameter in the contract is accountId, a string. Supplying accountId narrows the listing to automations belonging to that account; omitting it follows the contract as written, with accountId marked as not required. Before sending the request, confirm the token value is placed in the x-access-key header exactly as shown in the request sample titled List Comment Automations request, and confirm the trailing slash on the path is retained.

Authorization

Authentication is presented in the source under Authorization as a single header: x-access-key with a <token> value. The typed contract nodes do not supply an explicit required flag for this header, so this page shows the header exactly as presented without asserting requiredness beyond that presentation. When a request does not return 200, record the status code first, then read message, and do not assume a specific message string beyond the string type in the contract. The contract supplies only the success and message shape for 400 and 403, so no causal meaning is assigned to either status code here. The input contract table titled Authorization and query parameters summarizes the header and the accountId parameter together so both can be verified in one pass.

Query Parameters

The sole query parameter is accountId, typed as string and marked required=false in the typed contract. That means a client may call the endpoint without it, and when it is included the value should be the account identifier whose automations are wanted. Do not add pagination, sorting, or additional filter parameters, because none are part of this contract. The contract does not state what the endpoint returns when accountId is omitted, so no server-side behavior for omission is described here; each returned entry carries its own accountId field for identification.

Response Body: 200 application/json

A 200 response returns success as a boolean and automations as an array of automation objects. Each automation object carries id, accountId, platform, and name as required strings, plus status as a required string limited to active or paused. The createdAt and updatedAt fields are required date-time strings that show when the automation was created and last changed. As editorial reading guidance only, not as source-stated behavior, status can be read alongside stats: for example, a non-null lastError with a rising failed count is a combination a reader may choose to inspect first. The field map titled Response field map lists every field with its type and requiredness, and the worked example titled 200 response body shows the full shape to compare against a payload field by field.

Response Body: 400 application/json

A 400 response returns success as a boolean and message as a string, with no automations array. The supplied contract provides only this status code and body shape; it does not state what causes a 400, so this page does not assign a cause. Because the exact message strings are not part of the supplied contract, log the message verbatim for debugging and do not branch client logic on a guessed string. The failure matrix titled Status and response shape distinguishes 200, 400, and 403 by status and body shape only, so the three cases are not conflated.

Response Body: 403 application/json

A 403 response also returns success as a boolean and message as a string, with no automations array. The supplied contract provides only this status code and body shape; it does not state what causes a 403, so this page does not assign a cause or a permission meaning. As with 400, the message should be surfaced as-is and not matched against invented text. Keeping 400 and 403 handling separate by status code and shape prevents the two cases from being conflated, without claiming why either occurred.

Field map and worked example

Interpret each automation by reading its trigger, actions, and stats objects as a unit. In trigger, postScope is either any or specific; when it is specific, check platformPostId, postPermalink, and postId, each of which is a required string or null, to see which post identifier is populated. The keywords array holds the phrases that can trigger the automation, matchMode is one of exact, contains, or word, and excludeKeywords lists phrases that should prevent a match. In actions, publicReplies is an array of public reply templates and dmMessage is a single string for the direct message template. In stats, triggered, succeeded, and failed are required numbers, lastRunAt is a required string or null date-time for the most recent run, and lastError is a required string or null describing the most recent failure. The following reading notes are editorial interpretation, not source-stated behavior: a keyword appearing in both keywords and excludeKeywords may merit a closer look, and comparing an empty publicReplies array with a populated dmMessage can help a reader describe the configured actions. The field map titled Response field map lists every field with its type and requiredness, and the worked example titled 200 response body shows the full shape to compare against a real payload field by field.

Authorization and query parameters
NameInTypeRequiredNotes
x-access-keyheaderstring (<token>)As presented under Authorization; no explicit required flag suppliedAuthorization header identifier
accountIdquerystringNoSole query parameter; filters listing by account

accountId requiredness follows the typed contract (required=false). The x-access-key header is shown under Authorization in the source; no explicit required flag for the header is supplied in the typed contract nodes, so requiredness is not asserted beyond that presentation.

Response field map
FieldTypeRequiredValues / notes
successbooleanYesTop-level, all statuses
automationsarray<object>Yes200 only
automations[].idstringYes
automations[].accountIdstringYes
automations[].platformstringYes
automations[].namestringYes
automations[].statusstringYesactive | paused
automations[].triggerobjectYes
automations[].trigger.postScopestringYesany | specific
automations[].trigger.platformPostIdstring | nullYes
automations[].trigger.postPermalinkstring | nullYes
automations[].trigger.postIdstring | nullYes
automations[].trigger.keywordsarray<string>Yes
automations[].trigger.matchModestringYesexact | contains | word
automations[].trigger.excludeKeywordsarray<string>Yes
automations[].actionsobjectYes
automations[].actions.publicRepliesarray<string>Yes
automations[].actions.dmMessagestringYes
automations[].statsobjectYes
automations[].stats.triggerednumberYes
automations[].stats.succeedednumberYes
automations[].stats.failednumberYes
automations[].stats.lastRunAtstring | null (date-time)Yes
automations[].stats.lastErrorstring | nullYes
automations[].createdAtstring (date-time)Yes
automations[].updatedAtstring (date-time)Yes
messagestringYes400 and 403 only

Types, requiredness, nullability, and enums exactly as captured in the typed contract.

Status and response shape
StatusContent typeBody fieldsClient check
200application/jsonsuccess (boolean), automations (array<object>)Iterate automations; read trigger, actions, stats together
400application/jsonsuccess (boolean), message (string)Record status code; log message verbatim; do not branch on guessed strings
403application/jsonsuccess (boolean), message (string)Record status code; log message verbatim; do not branch on guessed strings

Exact 400/403 message strings and causal semantics for either status are not supplied; only the success/message shape is in the contract. No cause is assigned to 400 or 403.

List Comment Automations request
curl -X GET "{{API_BASE_URL}}/v1/comment-automations/" -H "x-access-key: <token>"
List Comment Automations request filtered by accountId
curl -X GET "{{API_BASE_URL}}/v1/comment-automations/?accountId=<accountId>" -H "x-access-key: <token>"
200 response body
{
  "success": true,
  "automations": [
    {
      "id": "string",
      "accountId": "string",
      "platform": "string",
      "name": "string",
      "status": "active",
      "trigger": {
        "postScope": "any",
        "platformPostId": "string",
        "postPermalink": "string",
        "postId": "string",
        "keywords": [
          "string"
        ],
        "matchMode": "exact",
        "excludeKeywords": [
          "string"
        ]
      },
      "actions": {
        "publicReplies": [
          "string"
        ],
        "dmMessage": "string"
      },
      "stats": {
        "triggered": 0,
        "succeeded": 0,
        "failed": 0,
        "lastRunAt": "2019-08-24T14:15:22Z",
        "lastError": "string"
      },
      "createdAt": "2019-08-24T14:15:22Z",
      "updatedAt": "2019-08-24T14:15:22Z"
    }
  ]
}
400 and 403 response body shape
{
  "success": true,
  "message": "string"
}
Interface fields
ScopeFieldTypeType referenceRequiredDescriptionConstraints
accountId#1accountIdstring__0No
response#2responseobject__0
response#2response.successboolean__1Yes
response#2response.automationsarray<object>__2Yes
response#2response.automations[]object__3
response#2response.automations[].idstring__4Yes
response#2response.automations[].accountIdstring__5Yes
response#2response.automations[].platformstring__6Yes
response#2response.automations[].namestring__7Yes
response#2response.automations[].statusstring__8Yes
response#2response.automations[].status[variant1]string__8_extends:__9kind: schemaValueIn; value: "active"
response#2response.automations[].status[variant2]string__8_extends:__10kind: schemaValueIn; value: "paused"
response#2response.automations[].triggerobject__11Yes
response#2response.automations[].trigger.postScopestring__12Yes
response#2response.automations[].trigger.postScope[variant1]string__12_extends:__13kind: schemaValueIn; value: "any"
response#2response.automations[].trigger.postScope[variant2]string__12_extends:__14kind: schemaValueIn; value: "specific"
response#2response.automations[].trigger.platformPostIdstring | null__15Yes
response#2response.automations[].trigger.platformPostId[variant1]string__15_extends:__16
response#2response.automations[].trigger.platformPostId[variant2]null__15_extends:__17
response#2response.automations[].trigger.postPermalinkstring | null__18Yes
response#2response.automations[].trigger.postPermalink[variant1]string__18_extends:__19
response#2response.automations[].trigger.postPermalink[variant2]null__18_extends:__20
response#2response.automations[].trigger.postIdstring | null__21Yes
response#2response.automations[].trigger.postId[variant1]string__21_extends:__22
response#2response.automations[].trigger.postId[variant2]null__21_extends:__23
response#2response.automations[].trigger.keywordsarray<string>__24Yes
response#2response.automations[].trigger.keywords[]string__25
response#2response.automations[].trigger.matchModestring__26Yes
response#2response.automations[].trigger.matchMode[variant1]string__26_extends:__27kind: ; value: "exact"
response#2response.automations[].trigger.matchMode[variant2]string__26_extends:__28kind: ; value: "contains"
response#2response.automations[].trigger.matchMode[variant3]string__26_extends:__29kind: ; value: "word"
response#2response.automations[].trigger.excludeKeywordsarray<string>__30Yes
response#2response.automations[].trigger.excludeKeywords[]string__31
response#2response.automations[].actionsobject__32Yes
response#2response.automations[].actions.publicRepliesarray<string>__33Yes
response#2response.automations[].actions.publicReplies[]string__34
response#2response.automations[].actions.dmMessagestring__35Yes
response#2response.automations[].statsobject__36Yes
response#2response.automations[].stats.triggerednumber__37Yes
response#2response.automations[].stats.succeedednumber__38Yes
response#2response.automations[].stats.failednumber__39Yes
response#2response.automations[].stats.lastRunAtstring | null__40Yes
response#2response.automations[].stats.lastRunAt[variant1]string__40_extends:__41kind: ; value: date-time
response#2response.automations[].stats.lastRunAt[variant2]null__40_extends:__42
response#2response.automations[].stats.lastErrorstring | null__43Yes
response#2response.automations[].stats.lastError[variant1]string__43_extends:__44
response#2response.automations[].stats.lastError[variant2]null__43_extends:__45
response#2response.automations[].createdAtstring__46Yeskind: ; value: date-time
response#2response.automations[].updatedAtstring__47Yeskind: ; value: date-time
response#3responseobject__0
response#3response.successboolean__1Yes
response#3response.messagestring__2Yes