Skip to Content
API ReferencePosts

Upload Management

This section documents the endpoints available for managing and retrieving information about your uploads.

Base URL

https://api.multi-upload-tool.com/api/v1

Authentication

All requests require an API Token in the header: x-api-key: YOUR_API_TOKEN

List Uploads

Retrieve a list of posts you have uploaded. Supports pagination and filtering.

Endpoint

GET /upload

Query Parameters

ParameterTypeRequiredDescription
pagenumberNoPage number (default: 1).
limitnumberNoItems per page (default: 100, max: 1000).
platformstringNoFilter by platform (tiktok, youtube).
statusstringNoFilter by status (pending, processing, completed, failed, scheduled).
searchstringNoSearch by title.
startDatestring (ISO)NoFilter by uploaded/scheduled/created on or after date.
endDatestring (ISO)NoFilter by uploaded/scheduled/created on or before date.

Example Request

curl -X GET "https://api.multi-upload-tool.com/api/v1/upload?page=1&limit=10&platform=tiktok" \
  -H "x-api-key: YOUR_API_TOKEN"

Example Response

{
  "success": true,
  "data": [
    {
      "id": 456,
      "title": "My amazing video",
      "platform": "tiktok",
      "status": "completed",
      "uploadedAt": "2023-10-27T10:00:00.000Z",
      "thumbnailUrl": "https://...",
      "videoUrl": "https://...",
      "fileSize": "12345678",
      "connectedAccount": {
        "id": "cmf3k9x2a0001l408q7vbn2hd",
        "platform": "tiktok",
        "accountName": "brand account",
        "profileImageUrl": "https://...",
        "tags": "team,marketing"
      },
      "metadata": { "videoId": "73123456789" }
    }
  ],
  "pagination": {
    "total": 50,
    "page": 1,
    "limit": 10,
    "totalPages": 5
  }
}

Get Upload Details

Retrieve details for a specific upload.

Endpoint

GET /upload/:id

Example Request

curl -X GET "https://api.multi-upload-tool.com/api/v1/upload/456" \
  -H "x-api-key: YOUR_API_TOKEN"

Example Response

{
  "success": true,
  "data": {
    "id": 456,
    "platform": "tiktok",
    "title": "My amazing video",
    "description": "Check this out!",
    "status": "completed",
    "uploadedAt": "2023-10-27T10:00:00.000Z",
    "thumbnailUrl": "https://...",
    "videoUrl": "https://...",
    "connectedAccount": {
      "id": "cmf3k9x2a0001l408q7vbn2hd",
      "platform": "tiktok",
      "accountName": "brand account",
      "profileImageUrl": "https://..."
    },
    "metadata": {
      "videoId": "73123456789",
      "shareUrl": "https://www.tiktok.com/@user/video/73123456789"
    }
  }
}

Update Upload

Update a scheduled upload, a draft or a post awaiting approval: its caption or its publish time. The status of a draft only changes through submit / approve. To send a failed upload again, use Retry a Failed Upload.

Endpoint

PATCH /upload/:id

Only uploads in scheduled status can be updated.

Body Parameters

ParameterTypeRequiredDescription
titlestringNoUpdate the title.
descriptionstringNoUpdate the description.
scheduledForstring (ISO)NoUpdate scheduled publish time.
statusstringNoNot editable here: a different value returns 400 USE_APPROVAL_ACTIONS. Use submit / approve for drafts, and cancel a scheduled post by deleting it.

Example Request

curl -X PATCH "https://api.multi-upload-tool.com/api/v1/upload/456" \
  -H "x-api-key: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "Updated Title", "scheduledFor": "2023-10-30T12:00:00.000Z"}'

Example Response

{
  "success": true,
  "data": {
    "id": 456,
    "title": "Updated Title",
    "status": "scheduled",
    "scheduledFor": "2023-10-30T12:00:00.000Z"
  }
}

Why an Upload Failed

A failed upload carries errorMessage (the platform’s words) and failure, the same information as data you can act on:

"status": "failed",
"errorMessage": "TikTok Error: Daily quota for active publishing users reached. (reached_active_user_cap)",
"failure": { "code": "rate_limited", "retryable": true, "nextAction": "retry_later" }

failure is null unless the upload failed.

X posts also carry xCredits: { "spent": 15, "refunded": 0, "net": 15 }, the credits the post cost (null until the job has run). See X credits.

coderetryablenextActionMeaning
rate_limitedtrueretry_laterA platform cap or rate limit (TikTok daily creator cap, too many posts in 24 hours, Facebook rate limit, YouTube upload quota). Retry once it resets.
account_disconnectedtruereconnect_accountThe platform refused the account’s access. Reconnect it, then retry.
platform_unavailabletrueretryThe platform timed out or dropped the connection.
queue_expiredtrueretryThe job waited more than 24 hours in the queue and was dropped.
unknowntrueretryNot recognized. Retry once; contact support if it fails again.
media_invalidfalsereplace_mediaThe platform refuses this file (format, resolution, duration, size).
media_unreachablefalsereplace_mediaThe media URL could not be downloaded.
content_flaggedfalseedit_postThe platform refused the content (flagged as spam, blocked link).
platform_processing_timeoutfalsecheck_platformThe platform received the video but did not finish processing it in time. It may still appear: check the account before retrying.
cancelledfalsenoneCancelled on purpose.

Retry a Failed Upload

Sends one failed upload again. An upload is one account of a post: when a post went out on 2 of 3 accounts, retrying the failed one never republishes the other two.

Endpoint

POST /upload/:id/retry

Body Parameters

ParameterTypeRequiredDescription
forcebooleanNoRetry even when failure.retryable is false. Use it only after checking the platform (e.g. platform_processing_timeout).

Example Request

curl -X POST "https://api.multi-upload-tool.com/api/v1/upload/456/retry" \
  -H "x-api-key: YOUR_API_TOKEN"

Example Response

{ "success": true, "data": { "uploadId": 456, "status": "pending" } }

When a retry is refused (409)

codeWhy
NOT_FAILEDOnly failed uploads can be retried.
ALREADY_RETRYINGThe upload is still being retried automatically. Wait for the result.
NOT_RETRYABLEfailure.retryable is false: retrying would fail again. Pass force: true to override.
ACCOUNT_INACTIVEReconnect the account first.
MEDIA_EXPIREDThe media of a failed upload is kept for 24 hours, then deleted. Create a new post.
DAILY_LIMITThe account reached its daily cap. The message says when it resets.
PLAN_LIMITA retried post counts toward your monthly quota again: the quota is used up, or your plan no longer includes this platform.
QUEUE_FULL / QUEUE_BUSYToo many uploads in progress. Try again in a few minutes.
{ "success": false, "error": "The account is not connected. Reconnect it, then retry.", "code": "ACCOUNT_INACTIVE" }

Retry All Failed Uploads

Sends again every retryable upload that failed in the last 24 hours. Uploads that were published are never touched.

Endpoint

POST /upload/retry-failed

Body Parameters

ParameterTypeRequiredDescription
accountIdstringNoOnly this account’s failed uploads.
platformstringNoOnly this platform’s failed uploads.

Example Response

{
  "success": true,
  "data": {
    "retried": [456, 457],
    "skipped": [
      { "uploadId": 458, "platform": "instagram", "code": "NOT_RETRYABLE", "reason": "Retrying will not fix this failure (media_invalid); next step: replace_media." }
    ]
  }
}

In the dashboard, the same actions are the Retry button on a failed post and Retry failed in the failures banner.

Get Upload Limits

Check upload limits for a specific account (e.g. YouTube daily quota).

Endpoint

GET /limits/:accountId

Example Request

curl -X GET "https://api.multi-upload-tool.com/api/v1/limits/cmf3k9x2a0001l408q7vbn2hd" \
  -H "x-api-key: YOUR_API_TOKEN"

Example Response

{
  "success": true,
  "data": {
    "remaining": 5,
    "limit": 10,
    "resetAt": "2023-10-28T00:00:00.000Z"
  }
}
AccountsBulk Upload