Targeting a Post

How to point analytics, comments and engagement requests at a post published through Onepostly or directly on the platform.

Analytics, comments, likes, reposts, bookmarks and quotes all identify their post with the same three parameters. Use them to target posts you published through Onepostly and posts published directly on the platform.

Selector Parameters

Prop

Type

GET and DELETE requests take these as query parameters. POST requests take them in the JSON body.

Choose a Selector

You have	Send	Targets
A Onepostly post id	`post`	Every destination of the post
A Onepostly post id and an account	`post` + `accountId`	The destination on that account
A destination id	`destinationId`	That destination
A native post id (for example an X post id)	`post` + `accountId`	That post on the account
A post URL	Call `/v1/posts/sync-external` first	The returned `externalPostId` with `accountId`

Reads (analytics, comment lists, repost lists) return one entry per destination in subjects. Writes (comment, like, repost, bookmark, quote) act on exactly one published destination: when the post has several, add accountId or destinationId, otherwise the request fails with AMBIGUOUS_TARGET.

import { Configuration, AnalyticsApi } from "@onepostly/sdk";

const analyticsApi = new AnalyticsApi(
  new Configuration({ apiKey: process.env.ONEPOSTLY_API_KEY })
);

const response = await analyticsApi.getAnalytics({
  post: "1960956321831854280",
  accountId: "YOUR_X_ACCOUNT_ID",
  metrics: "views,reach,profile_views",
  period: "day",
});
console.log(response);

{
  "analytics": {
    "post": "1699f415-7fb6-43f4-9d2a-c447491f32a8",
    "status": "ready",
    "fetchedAt": "2026-08-25T10:00:00.000Z",
    "subjects": [
      {
        "scope": "destination",
        "subjectId": "d4e5f6a7-8b9c-4d0e-8f1a-2b3c4d5e6f7a",
        "accountId": "a1b2c3d4-e5f6-4a7b-8c9d-e0f1a2b3c4d5",
        "platform": "instagram",
        "externalPostId": "17895695668004550",
        "status": "ready",
        "metrics": {
          "impressions": 1234,
          "reach": 987,
          "likes": 123,
          "comments": 12,
          "shares": 4,
          "saves": 2,
          "plays": 456,
          "engagement": 0.14
        },
        "fetchedAt": "2026-08-25T10:00:00.000Z",
        "expiresAt": "2026-09-01T10:00:00.000Z",
        "error": null
      }
    ]
  }
}

Outside Posts

A post published directly on the platform, not through Onepostly, works with the native post id plus accountId. Onepostly looks the post up on first use, so you can pass the native id straight away.

To find a post by URL, or to list an account's recent posts, call POST /v1/posts/sync-external with accountId and:

url: the post URL. The response has found and post, including post.externalPostId.
postId: the native post id, to confirm the post exists.
Neither: returns the account's 20 most recent posts in posts.

import { Configuration, PostsApi } from "@onepostly/sdk";

const postsApi = new PostsApi(
  new Configuration({ apiKey: process.env.ONEPOSTLY_API_KEY })
);

const response = await postsApi.syncExternal({
  syncExternalBody: {
    "accountId": "YOUR_THREADS_ACCOUNT_ID",
    "url": "https://www.threads.com/@you/post/DbNQAb8ABC1"
  },
});
console.log(response);

{
  "synced": {
    "postsFound": 1,
    "postsSynced": 1,
    "skipped": false
  },
  "found": true,
  "post": {
    "id": "e8f9a0b1-c2d3-4e5f-8a6b-c7d8e9f0a1b2",
    "accountId": "a1b2c3d4-e5f6-4a7b-8c9d-e0f1a2b3c4d5",
    "platform": "threads",
    "externalPostId": "DbNQAb8ABC1",
    "externalUrl": "https://www.threads.com/@you/post/DbNQAb8ABC1",
    "mediaKind": "text",
    "publishedAt": "2026-08-25T10:00:00.000Z",
    "syncedAt": "2026-08-25T10:00:00.000Z",
    "analyticsStatus": "ready"
  }
}

A url or postId lookup finds the post only if it is among the account's 20 most recent posts. For older posts, pass the native id directly as post.
Calls for the same account less than 15 seconds apart return synced.skipped: true and only posts Onepostly already knows. If a single-post lookup returns found: false with skipped: true, call again after 15 seconds.
Supported for X, Instagram, Facebook, Threads, YouTube, TikTok and Bluesky. LinkedIn and Pinterest return UNSUPPORTED_PLATFORM.

Errors

Code	Cause	Fix
`VALIDATION_ERROR`	No `post` or `destinationId`; `destinationId` belongs to a different `accountId`; or both `url` and `postId` sent to sync.	Send a selector from Choose a Selector.
`ACCOUNT_REQUIRED`	`post` is not a Onepostly post id and no `accountId` was sent.	Add the `accountId` that published the native post.
`ACCOUNT_NOT_FOUND`	`accountId` does not exist in the workspace.	Use an id from List Connections.
`NOT_FOUND`	The Onepostly post does not exist or has no destinations.	Check the post id.
`DESTINATION_NOT_FOUND`	No destination matches `destinationId`, or the post has no destination on `accountId`.	Check the ids in the post response.
`NOT_PUBLISHED`	A write targets a post with no published destination.	Wait for the post to publish, then try again.
`AMBIGUOUS_TARGET`	A write targets a post with several published destinations.	Add `accountId` or `destinationId`.
`CONNECTION_INACTIVE`	The account needs reconnecting before Onepostly can read its outside posts.	Reconnect the account.
`TOKEN_INVALID`	The platform rejected the account's authorization during a sync.	Reconnect the account.
`PERMISSION_DENIED`	The account lacks the permission to list its posts.	Reconnect and grant all requested permissions.
`UNSUPPORTED_PLATFORM`	Sync is not available for this platform.	Use a Onepostly post id instead.
`TARGET_SYNC_FAILED`, `LIST_FAILED`, `SYNC_FAILED`	The platform did not return the post or the post list.	Try again later.

Selector ParametersCopy Anchor Link

Choose a SelectorCopy Anchor Link

Outside PostsCopy Anchor Link

ErrorsCopy Anchor Link

On this page

Selector Parameters

Choose a Selector

Outside Posts

Errors