Posts & Comments

List top-level post comments

Lists only top-level comments on a verified own TikTok post, not complete reply pagination; other providers return 501 unsupported_by_provider. Send post_id and pagination in JSON; limit defaults to 20, range 1–50. Confirmed absence returns 404 post_not_found (39000); 403 post_inaccessible (39005) is not absence and does not identify the cause. Incomplete verification is a retryable failure. Other read failures return 502 list_post_comments_failed (39003), preserving provider error classifications.

POSThttps://api.unifyport.ai/v1/accounts/{account_id}/posts/comments/list

Supported channels

TikTok

Before you call

Use a server-side X-Api-Key for the workspace that owns the resource. Replace every placeholder before running a sample.

Prepare your parameters

account_id: Use data.id from account creation or an account query. Account identifiers belong to the workspace selected by X-Api-Key. Get account

Request

curl -X POST "https://api.unifyport.ai/v1/accounts/{account_id}/posts/comments/list" \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"post_id":"7500000000000000101","limit":20}'

Request parameters

Headers

X-Api-Key

stringrequired

Workspace API key. The workspace is resolved from this header.

Content-Type

stringrequired

Use application/json when sending a JSON request body.

Path parameters

account_id

stringrequired

Identifier used in the accounts route.

Request body

post_id

stringrequired

Provider post ID, passed unchanged as a string. TikTok requires a positive decimal integer string without leading zeros; otherwise 400 provider_invalid_request.

minLength: 1 · pattern: \S

cursor

string

Pass the previous next_cursor unchanged; omit for the first page. Empty strings are invalid.

minLength: 1

limit

integer

Page size from 1 to 50; defaults to 20.

minimum: 1 · maximum: 50

Understand the result

Read the documented response fields and HTTP status, then follow the related operations for your next step.

Response 200 OK

{
  "request_id": "<REQUEST_ID>",
  "data": {
    "items": [],
    "has_more": false
  }
}

Response body

id

string

Provider identifier; preserve the non-blank string verbatim, never convert it to a number.

minLength: 1 · pattern: \S

post_id

string

Provider identifier; preserve the non-blank string verbatim, never convert it to a number.

minLength: 1 · pattern: \S

text

string

Original text when reliably available, including an empty string; omitted when unknown.

author

object

Author information, when available.

id

string

Provider identifier; preserve the non-blank string verbatim, never convert it to a number.

minLength: 1 · pattern: \S

display_name

string

Original text when reliably available, including an empty string; omitted when unknown.

avatar_url

string

Reliably obtained non-empty avatar URL; omitted when unknown.

minLength: 1

created_at

string

Reliable comment creation time in RFC3339 UTC; omitted when unknown, never replaced with observation time.

format: date-time

parent_comment_id

string

Provided only when the parent-child relationship is confirmed. Absence does not prove this is a replyable top-level comment.

minLength: 1 · pattern: \S

has_more

boolean

Whether another page is available.

next_cursor

string

Opaque cursor returned only when has_more=true; pass unchanged for the next page. Omitted on the last page.

minLength: 1

Responses

200

200 OK

Request succeeded. See the example response body.

400

Bad Request

The request body, path, or parameters are invalid.

401

Unauthorized

The X-Api-Key header is missing or invalid.

403

Forbidden

The request is authenticated but is not allowed.

404

Not Found

The requested resource was not found. Check error.code and the current operation.

409

Conflict

The requested operation conflicts with an existing provider account or resource.

501

Not Implemented

The selected provider does not implement this operation.

502

Bad Gateway

The provider adapter or upstream provider could not complete the operation.

If the request fails

Inspect HTTP status and error.code/numeric_code, and keep request_id for diagnosis. Correct invalid parameters, complete required authorization or check runtime state as appropriate. Confirm the outcome before retrying a send or another write. Error reference

Read HTTP status, error.code and error.numeric_code together in the context of the current operation. Numeric codes are strings. Keep request_id for diagnosis; it is not an idempotency key or a task identifier.

invalid_request · 10000 · 400

Check the JSON body and required fields.

What to do: Correct the parameters for this operation and channel before requesting again. Repeating an unchanged invalid request will not resolve the error.

Illustrative JSON; message varies with the actual cause · 400 · 10000

{
  "request_id": "req_example",
  "error": {
    "code": "invalid_request",
    "numeric_code": "10000",
    "message": "Invalid request parameters"
  }
}

invalid_target_workspace · 11003 · 400

The workspace override target is empty or malformed. Remove the override header and use the API key belonging to the intended workspace.

When it occurs: Applies when the request includes the X-Workspace-Id workspace override header.

What to do: Correct the parameters for this operation and channel before requesting again. Repeating an unchanged invalid request will not resolve the error.

Illustrative JSON; message varies with the actual cause · 400 · 11003

{
  "request_id": "req_example",
  "error": {
    "code": "invalid_target_workspace",
    "numeric_code": "11003",
    "message": "Invalid target workspace"
  }
}

provider_invalid_request · 30001 · 400

Check the channel-specific fields and formats.

What to do: Correct the parameters for this operation and channel before requesting again. Repeating an unchanged invalid request will not resolve the error.

Illustrative JSON; message varies with the actual cause · 400 · 30001

{
  "request_id": "req_example",
  "error": {
    "code": "provider_invalid_request",
    "numeric_code": "30001",
    "message": "Provider rejected the request"
  }
}

invalid_api_key · 11001 · 401

Check whether the API key is correct and enabled.

What to do: Keep request_id and the structured codes, and investigate the current operation before taking another action.

Illustrative JSON; message varies with the actual cause · 401 · 11001

{
  "request_id": "req_example",
  "error": {
    "code": "invalid_api_key",
    "numeric_code": "11001",
    "message": "Invalid API key"
  }
}

missing_api_key · 11000 · 401

Add the X-Api-Key header.

What to do: Keep request_id and the structured codes, and investigate the current operation before taking another action.

Example · 401 · 11000

{
  "request_id": "req_xxx",
  "error": {
    "code": "missing_api_key",
    "numeric_code": "11000",
    "message": "Missing X-Api-Key header"
  }
}

post_inaccessible · 39005 · 403

Check the account and the target identifiers actually required by this endpoint. post_not_found confirms that the post is missing. comment_not_found means the target top-level comment was not found after verification, not that all replies were searched. post_inaccessible means inaccessible; it does not prove absence or identify the cause. Keep the error and investigate before choosing the next action.

What to do: Check the target identifier, resource ownership and current workspace. Do not treat a confirmed missing or inaccessible target as a temporary service failure to retry automatically.

Illustrative JSON; message varies with the actual cause · 403 · 39005

{
  "request_id": "req_example",
  "error": {
    "code": "post_inaccessible",
    "numeric_code": "39005",
    "message": "Post is not accessible"
  }
}

workspace_override_forbidden · 11002 · 403

The request attempts a workspace override that this API key is not allowed to use. Remove the override header and use the API key belonging to the intended workspace.

When it occurs: Applies when the request includes the X-Workspace-Id workspace override header.

What to do: Keep request_id and the structured codes, and investigate the current operation before taking another action.

Illustrative JSON; message varies with the actual cause · 403 · 11002

{
  "request_id": "req_example",
  "error": {
    "code": "workspace_override_forbidden",
    "numeric_code": "11002",
    "message": "Workspace override is not allowed"
  }
}

account_not_found · 20020 · 404

Check account_id and use an X-Api-Key for the workspace that owns the account. An account not found in this workspace cannot be accessed with this key.

What to do: Check the target identifier, resource ownership and current workspace. Do not treat a confirmed missing or inaccessible target as a temporary service failure to retry automatically.

Illustrative JSON; message varies with the actual cause · 404 · 20020

{
  "request_id": "req_example",
  "error": {
    "code": "account_not_found",
    "numeric_code": "20020",
    "message": "Account not found"
  }
}

post_not_found · 39000 · 404

What to do: Check the target identifier, resource ownership and current workspace. Do not treat a confirmed missing or inaccessible target as a temporary service failure to retry automatically.

Illustrative JSON; message varies with the actual cause · 404 · 39000

{
  "request_id": "req_example",
  "error": {
    "code": "post_not_found",
    "numeric_code": "39000",
    "message": "Post not found"
  }
}

target_workspace_not_found · 11004 · 404

The overridden workspace was not found or is unavailable. Verify workspace ownership, remove the override header and use the intended workspace’s API key; repeated requests do not grant access.

When it occurs: Applies when the request includes the X-Workspace-Id workspace override header.

What to do: Check the target identifier, resource ownership and current workspace. Do not treat a confirmed missing or inaccessible target as a temporary service failure to retry automatically.

Illustrative JSON; message varies with the actual cause · 404 · 11004

{
  "request_id": "req_example",
  "error": {
    "code": "target_workspace_not_found",
    "numeric_code": "11004",
    "message": "Target workspace not found"
  }
}

account_binding_not_found · 30006 · 409

The account has no active channel connection binding; check its status.

What to do: Query authorization and runtime status, then choose refresh, start or reconnect only when appropriate for the intended state and channel. A connection problem alone does not prove logout. Confirm running before dependent business operations.

Illustrative JSON; message varies with the actual cause · 409 · 30006

{
  "request_id": "req_example",
  "error": {
    "code": "account_binding_not_found",
    "numeric_code": "30006",
    "message": "Account is not bound to an available server"
  }
}

provider_not_ready · 30009 · 409

The connection is not ready. Check authorization and runtime_status before retrying.

Illustrative JSON; message varies with the actual cause · 409 · 30009

{
  "request_id": "req_example",
  "error": {
    "code": "provider_not_ready",
    "numeric_code": "30009",
    "message": "Provider client is not ready"
  }
}

unsupported_by_provider · 30003 · 501

The channel does not support this operation; choose a supported operation.

What to do: Use a channel and action listed as supported. Repeating the same request does not add capabilities or grant beta access.

Example · 501 · 30003

{
  "request_id": "req_xxx",
  "error": {
    "code": "unsupported_by_provider",
    "numeric_code": "30003",
    "message": "Operation not supported by this provider"
  }
}

list_post_comments_failed · 39003 · 502

List top-level post comments: the service could not produce a valid query result.

What to do: Keep request_id and check the requested identifiers and account access. Retry this read only after checking the cause; a failed query does not prove an empty or missing resource.

Illustrative JSON; message varies with the actual cause · 502 · 39003

{
  "request_id": "req_example",
  "error": {
    "code": "list_post_comments_failed",
    "numeric_code": "39003",
    "message": "Failed to list post comments"
  }
}

provider_unavailable · 30002 · 502

The channel service is unavailable. Check status or try again later; confirm the result before retrying writes.

What to do: Keep request_id and check the requested identifiers and account access. Retry this read only after checking the cause; a failed query does not prove an empty or missing resource.

Example · 502 · 30002

{
  "request_id": "req_example_provider_unavailable",
  "error": {
    "code": "provider_unavailable",
    "numeric_code": "30002",
    "message": "Provider service unavailable"
  }
}