Upload Status
Check the status of asynchronous uploads initiated with async_upload=true or scheduled posts.
Endpoint
GET /api/uploadposts/status?request_id=yourrequestid
GET /api/uploadposts/status?job_id=yourjobid
Headers
| Name | Value | Description |
|---|---|---|
| Authorization | Apikey your-api-key-here | Your API key for authentication |
Query Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| request_id | String | Conditional | The request identifier returned by the upload endpoints when async_upload=true. Use for async uploads. You can also provide your own request_id when submitting the upload (via form field or X-Request-Id header) so you can poll status even if the upload response is lost due to a timeout. |
| job_id | String | Conditional | The job identifier returned by scheduled posts. Use for posts with scheduled_date. |
Note: At least one of request_id or job_id must be provided.
The response echoes back the external_id you supplied when creating the post
(null when you didn't send one), so you can match a status poll to a record in
your own system. See
Scheduled Posts.
Behavior
-
Async uploads: When you submit an upload request with
async_upload=true, the API returns immediately with arequest_id. Use this to retrieve aggregated progress and results. -
Scheduled posts: When you schedule a post with
scheduled_date, the API returns ajob_id. Use this to check the status after the scheduled time. -
The top-level
statusfield may be one of:pending: The request has been accepted but no platform results have been recorded yet. For scheduled posts, this means the job has not executed yet.queued: The upload is queued and waiting for a worker to begin processing.processing: At least one platform is actively being processed while others are still queued or pending.in_progress: Some platform results have been recorded but not all.completed: All platforms have finished successfully.failed: All platforms have failed, or no activity has been recorded for over 1 hour.not_found: No upload request was found with the provided ID (returned with HTTP 404).
-
Individual platform results may have their own status:
queued: The platform upload is waiting to be processed.processing: The platform upload is currently being processed.completed: The platform upload finished successfully.failed: The platform upload failed permanently.retryable: The platform upload failed but is eligible for automatic retry.skipped: The platform was never attempted because the profile has no account connected for it. The entry also carriesskipped: trueandskip_reason: "profile_platform_not_configured". Skipped platforms count towardscompleted, so a request whose connected platforms all finished is reported ascompletedeven if one platform was skipped. See Unconnected platforms.
-
TikTok inbox fallback: a TikTok result may include
"fallback_to_inbox": true. The upload succeeded, but because of TikTok's daily active-user cap it was delivered to the account's inbox/drafts instead of being published live — the owner must open the TikTok app to publish it. Video drafts usually showpost_url: "Video sent to Inbox (No Public URL)"; photo drafts havepost_url: null, so rely on the flag. See the reached_active_user_cap guide for details. -
TikTok post ID released late: TikTok only releases a video's public post ID once its moderation finishes, which can take hours. When that outlasts the publish check, the TikTok result is a success with
post_url: null,platform_post_idset to TikTok's temporary publish id, and awarningsentry saying the ID will follow. Upload-Post keeps asking TikTok for up to 24 hours; as soon as the ID arrives, the same result in Upload Status and Upload History gets the realplatform_post_idandpost_url, the warning is removed andpost_id_resolved_late: trueis added. No new webhook is sent for that change, so read the status or history again to pick it up. -
TikTok internal errors are not republished: when TikTok answers a publish with an internal error, Upload-Post checks the account's videos for about 2 minutes. If the video shows up, the result is a success; if not, the result is a failure with an explicit message ("TikTok received the video but answered with an internal error…") and the video is not published again automatically, because TikTok sometimes publishes it once moderation finishes. Check the TikTok profile before uploading it again.
Example Request
For async uploads:
curl \
-H 'Authorization: Apikey your-api-key-here' \
"https://api.upload-post.com/api/uploadposts/status?request_id=<REQUEST_ID>"
For scheduled posts:
curl \
-H 'Authorization: Apikey your-api-key-here' \
"https://api.upload-post.com/api/uploadposts/status?job_id=<JOB_ID>"
Example Response
For async uploads (request_id) — in progress:
{
"request_id": "7b2c2f5e-1234-4a6f-9f1d-a1b2c3d4e5f6",
"external_id": "clip-4821",
"status": "in_progress",
"completed": 1,
"total": 2,
"results": [
{
"platform": "x",
"success": true,
"message": "Queued",
"upload_timestamp": "2025-01-01T12:34:56Z"
}
],
"last_update": "2025-01-01T12:34:56Z"
}
For scheduled posts (job_id):
{
"job_id": "job_abc123xyz",
"status": "completed",
"completed": 2,
"total": 2,
"results": [
{
"platform": "x",
"success": true,
"message": "Published",
"upload_timestamp": "2025-01-15T14:00:00Z"
},
{
"platform": "linkedin",
"success": true,
"message": "Published",
"upload_timestamp": "2025-01-15T14:00:05Z"
}
],
"last_update": "2025-01-15T14:00:05Z"
}
Failed upload:
{
"request_id": "ae8e8d98-dead-40bd-a206-8bacc9efea84",
"status": "failed",
"message": "Upload appears to have failed (no activity for over 1 hour)",
"completed": 0,
"total": 1,
"results": []
}
Not found:
{
"request_id": "nonexistent-id",
"status": "not_found",
"message": "No upload request found with this ID"
}
Responses
| Status | Description |
|---|---|
| 200 OK | Success. Response includes request_id or job_id depending on which parameter was used. |
| 400 Bad Request | Missing both request_id and job_id: {"error":"request_id or job_id is required"} |
| 401 Unauthorized | Invalid or expired token |
| 404 Not Found | No upload request found with the provided ID |
| 500 Internal Server Error | Server error with details |
SDK Examples
Python
from upload_post import UploadPostClient
client = UploadPostClient(api_key="your-api-key-here")
# Check status of an async upload
status = client.get_status("request_id_from_upload")
# Check status of a scheduled or queued post
status = client.get_job_status("job_id_from_scheduled_post")
JavaScript/Node.js
import { UploadPost } from 'upload-post';
const client = new UploadPost('your-api-key-here');
// Check status of an async upload
const status = await client.getStatus('request_id_from_upload');
// Check status of a scheduled or queued post
const jobStatus = await client.getJobStatus('job_id_from_scheduled_post');
Polling Best Practices
The status endpoint uses internal caching. Polling faster than the cache refresh interval returns the same result and wastes your rate limit budget.
| Status | Cache TTL | Recommended poll interval |
|---|---|---|
queued / pending | 2 seconds | Every 5–10 seconds |
processing | 3 seconds | Every 10 seconds |
completed / failed | 5 minutes | Stop polling — result is final |
For high-volume integrations, consider using webhooks instead of polling — you'll receive an instant POST notification when the upload completes.
See the full Rate Limits & Polling guide for detailed recommendations.