Upload History

Retrieve a paginated list of your past uploads across platforms.

Endpoint

GET /api/uploadposts/history

Headers

Name	Value	Description
Authorization	Apikey your-api-key	Required.

Query Parameters

Name	Type	Required	Default	Allowed	Description
page	Integer	No	1	>= 1	Page number
limit	Integer	No	10	10, 20, 50, 100	Page size
platform	String	No	—	`tiktok`, `instagram`, `youtube`, `facebook`, `linkedin`, `x`, `threads`, `reddit`, `pinterest`, `bluesky`, `google_business`, `discord`, `telegram`, …	Only rows for this platform
status	String	No	—	`success`, `failed`	Only successful or only failed rows
profile_username	String	No	—	any profile `username`	Only rows of this profile (`profile` is accepted as an alias)
request_id	String	No	—	≤ 200 chars	Exact match. All rows produced by one upload request (one per platform)
job_id	String	No	—	≤ 200 chars	Exact match. All rows produced by one scheduled/async job
external_id	String	No	—	≤ 200 chars	Exact match. Rows of the post you tagged with this `external_id` when creating it
start	Date	No	—	`YYYY-MM-DD` or ISO 8601	Start of the date range (requires `end`)
end	Date	No	—	`YYYY-MM-DD` or ISO 8601	End of the date range (requires `start`; max 2 months)

Filters combine with AND. The exact-match ids are scoped to your account, so looking up an id that belongs to another account returns an empty page, not an error. The same filters apply to the in_progress list.

Look up one request / job / external id

# every platform row of one upload request
curl "https://api.upload-post.com/api/uploadposts/history?request_id=req_123&limit=10" \
  -H "Authorization: Apikey your-api-key"

# the post you tagged with your own id
curl "https://api.upload-post.com/api/uploadposts/history?external_id=cms-post-8841&limit=10" \
  -H "Authorization: Apikey your-api-key"

# one profile's failed uploads this week
curl "https://api.upload-post.com/api/uploadposts/history?profile_username=acme&status=failed&start=2026-08-18&end=2026-08-25&limit=50" \
  -H "Authorization: Apikey your-api-key"

Responses

200 OK
- history: array of history items (most recent first)
- in_progress: uploads still running (last 24h), same filters applied
- total: total number of records for the user
- page: requested page
- limit: requested limit
400 Bad Request: { "error": "Invalid page" }, { "error": "Invalid limit" }, { "error": "Invalid request_id" } (id longer than 200 chars or with control characters), or a date-range error
401 Unauthorized: { "success": false, "message": "Invalid or expired token" }
500 Internal Server Error: { "error": "Failed to retrieve upload history", "details": "..." }

History Item Schema

Typical fields (not all fields are guaranteed on every record):

user_email: string
profile_username: string
platform: string (e.g., tiktok, instagram, linkedin, youtube, facebook, x, threads, pinterest, google_business, discord, telegram)
media_type: string (video | photo | text)
upload_timestamp: string (ISO-8601)
success: boolean
platform_post_id: string | array | null
post_url: string | null (present when success is true)
error_message: string | null
media_size_bytes: number | null
post_title: string | null
post_caption: string | null
is_async: boolean | null
job_id: string | null (present when the upload originated from a scheduled job)
dashboard: any | null
video_was_transcoded: boolean | null
changes: object | null
prevalidation_metadata: object | null
request_id: string | null
external_id: string | null (the identifier you supplied when creating the post; absent when you didn't send one)
request_total_platforms: number | null
fallback_to_inbox: boolean (TikTok only; true when the post succeeded but was delivered to the account's inbox/drafts because of TikTok's daily active-user cap — it is not live until published from the TikTok app. Absent on records from before August 2026; for those, a video inbox delivery usually shows post_url: "Video sent to Inbox (No Public URL)", while photo inbox deliveries have post_url: null. See the reached_active_user_cap guide.)

Scheduled posts include job_id on the history item — that is how you match the job to the publish record. To match a row in your own system, send external_id when you create the post and read it back here; post_title is editable and a bad key. See Scheduled Posts.

Example Request

curl -X GET "https://api.upload-post.com/api/uploadposts/history?page=1&limit=20" \
  -H "Authorization: Apikey your-api-key"

Example 200 Response (truncated)

{
  "history": [
    {
      "user_email": "[email protected]",
      "profile_username": "profile_username",
      "platform": "instagram",
      "media_type": "video",
      "upload_timestamp": "2025-09-04T10:22:33.123Z",
      "success": true,
      "platform_post_id": "1789654321",
      "post_url": "https://instagram.com/p/abc123",
      "media_size_bytes": 12345678,
      "post_title": "Title",
      "post_caption": "Description",
      "is_async": false,
      "job_id": "a1b2c3d4e5f67890a1b2c3d4e5f67890",
      "dashboard": true,
      "request_id": "req_123",
      "request_total_platforms": 3
    }
  ],
  "total": 42,
  "page": 1,
  "limit": 20
}

Endpoint​

Headers​

Query Parameters​

Look up one request / job / external id​

Responses​

History Item Schema​

Example Request​

Example 200 Response (truncated)​

See also​