Skip to main content
The Post History Import API allows you to retrieve past posts from your connected social media accounts with analytics snapshot. The import process is asynchronous:
  1. You request an import for a specific social account.
  2. The system queues the job and processes it in the background.
  3. You can poll the status of the import.
  4. Once completed, you can retrieve the imported posts and their analytics.
Limits: There is a monthly limit on the number of posts you can import per social account, depending on your subscription tier.
  • Free: 5 posts / month
  • Pro: 100 posts / month
  • Business: 250 posts / month
  • We can set custom limits depending on your needs
The maximum number of posts you can request in a single API call is 100.

​
Step 1: Start an Import

Initiate a new import job. You must specify the team ID and the social account type. Endpoint: POST /api/v1/post-history-import Parameters
  • teamId (required) — The ID of the team where the social account is connected.
  • socialAccountType (required) — The platform to import from. Supported values: FACEBOOK, INSTAGRAM, THREADS, TIKTOK, YOUTUBE, LINKEDIN, PINTEREST, REDDIT, MASTODON, BLUESKY.
  • count (required) — Number of posts to import (max 100 in one import).
  • withAnalytics (optional) — Whether to fetch analytics data for the posts (default: true).
Response Returns the created import object with a PENDING status. 
{
  "id": "import_12345",
  "teamId": "team_abc123",
  "socialAccountId": "social_xyz789",
  "requestedCount": 50,
  "withAnalytics": true,
  "status": "PENDING",
  "postsImported": 0,
  "analyticsImported": 0,
  "createdAt": "2024-01-01T12:00:00Z"
}
Example 
const importJob = await bundlesocial.postImport.create({
  requestBody: {
    teamId: 'team_abc123',
    socialAccountType: 'INSTAGRAM',
    count: 50,
    withAnalytics: true
  }
});

​
Step 2: Check Import Status

You can check the progress of your imports. The status can be PENDING, FETCHING_POSTS, FETCHING_ANALYTICS, COMPLETED, FAILED, or RATE_LIMITED. Endpoint: GET /api/v1/post-history-import Query Parameters
  • teamId (required)
  • socialAccountType (optional) — Filter by platform.
Response Returns a list of import jobs. 
{
  "imports": [
    {
      "id": "import_12345",
      "status": "COMPLETED",
      "postsImported": 50,
      "analyticsImported": 50,
      "completedAt": "2024-01-01T12:05:00Z"
      // ... other fields
    }
  ]
}
Get a specific import Endpoint: GET /api/v1/post-history-import/{importId}

​
Step 3: Retrieve Imported Posts

Once the import is COMPLETED, you can fetch the posts. Endpoint: GET /api/v1/post-history-import/posts Query Parameters
  • teamId (required)
  • socialAccountType (required)
  • limit (optional) — Max number of posts to return (default 50, max 100).
  • offset (optional) — Pagination offset (default 0).
Response Returns the list of posts along with usage limits. 
{
  "posts": [
    {
      "externalId": "123456789",
      "title": "My Post",
      "description": "Post caption...",
      "thumbnail": "https://...",
      "permalink": "https://instagram.com/p/...",
      "publishedAt": "2023-12-25T10:00:00Z",
      "analytics": {
        "likes": 150,
        "comments": 10,
        "impressions": 2000
      }
    }
    // ... more posts
  ],
  "total": 50,
  "limit": 100,
  "remainingCapacity": 50
}

​
Step 4: Retry (If needed)

If an import fails (e.g., due to temporary network issues), you can retry it. Endpoint: POST /api/v1/post-history-import/{importId}/retry Body
  • teamId (required)

​
Handling Rate Limits

If an import enters the RATE_LIMITED status, it means the social platform’s API rate limits have been hit. The system will automatically pause and may retry later, or you can manually retry after the rateLimitResetAt time passed.