Skip to main content

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​

NameValueDescription
AuthorizationApikey your-api-key-hereYour API key for authentication

Query Parameters​

NameTypeRequiredDescription
request_idStringConditionalThe 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_idStringConditionalThe 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.

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.

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",
  "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​

StatusDescription
200 OKSuccess. Response includes request_id or job_id depending on which parameter was used.
400 Bad RequestMissing both request_id and job_id: {"error":"request_id or job_id is required"}
401 UnauthorizedInvalid or expired token
404 Not FoundNo upload request found with the provided ID
500 Internal Server ErrorServer 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.

StatusCache TTLRecommended poll interval
queued / pending2 secondsEvery 5–10 seconds
processing3 secondsEvery 10 seconds
completed / failed5 minutesStop 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.