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 a request_id. Use this to retrieve aggregated progress and results.

• Scheduled posts: When you schedule a post with scheduled_date, the API returns a job_id. Use this to check the status after the scheduled time.

• The top-level status field 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 carries skipped: true and skip_reason: "profile_platform_not_configured". Skipped platforms count towards completed, so a request whose connected platforms all finished is reported as completed even 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 show post_url: "Video sent to Inbox (No Public URL)"; photo drafts have post_url: null, so rely on the flag. See the reached_active_user_cap guide for details.

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.

Related

• Text uploads
• Video uploads
• Photo uploads
• Schedule posts
• Rate Limits & Polling