Uploading Media

The API offers two ways to upload media to your Content Library:

• From a URL: uploadMediaFromUrl, when your file is already hosted at a public URL.
• From a local file: startMediaUpload + completeMediaUpload, when the file lives on disk.

Images, videos, and GIFs are supported. Direct uploads are capped at 500 MiB per file.

Uploading Media from a URL

Adds a file to your Content Library from a public URL.

mutation uploadMediaFromUrl(
  $url: String!
  $name: String
  $mediaLabelIds: [ID]
) {
  uploadMediaFromUrl(
    url: $url
    name: $name
    mediaLabelIds: $mediaLabelIds
  ) {
    success
    media {
      id
      name
      url
      mimeType
      size
    }
    errors {
      field
      code
      message
    }
  }
}

{
  "url": "https://example.com/images/hero.jpg",
  "name": "campaign-hero.jpg",
  "mediaLabelIds": ["1182", "1235"]
}

{
  "data": {
    "uploadMediaFromUrl": {
      "success": true,
      "media": {
        "id": "1001",
        "name": "campaign-hero.jpg",
        "url": "https://cdn.example.com/1a2b3c4d/",
        "mimeType": "image/jpeg",
        "size": 482912
      },
      "errors": []
    }
  }
}

Direct Upload

When your file is on disk, upload it in three steps.

mutation startMediaUpload($size: BigInt!, $mimeType: String!) {
  startMediaUpload(size: $size, mimeType: $mimeType) {
    success
    uploadToken
    uploadUrl
    expiresAt
    errors {
      field
      code
      message
    }
  }
}

{
  "size": 2048576,
  "mimeType": "image/jpeg"
}

{
  "data": {
    "startMediaUpload": {
      "success": true,
      "uploadToken": "b3f1c2a4-9d5e-4c7b-8a1f-2e6d0c9a7b12",
      "uploadUrl": "https://uploads.example.com/...&signature=...",
      "expiresAt": "2025-02-01T15:30:00Z",
      "errors": []
    }
  }
}

curl --request PUT \
--upload-file ./campaign-hero.jpg \
--header 'Content-Length: 2048576' \
--header 'Content-Type: image/jpeg' \
--header 'If-None-Match: *' \
"https://uploads.example.com/...&signature=..."

import requests

with open('./campaign-hero.jpg', 'rb') as f:
  response = requests.put(
      'https://uploads.example.com/...&signature=...',
      data=f,
      headers={
          'Content-Type': 'image/jpeg',
          'If-None-Match': '*',
      },
  )

response.raise_for_status()

import { readFile } from 'node:fs/promises';

const file = await readFile('./campaign-hero.jpg');

const response = await fetch('https://uploads.example.com/...&signature=...', {
method: 'PUT',
headers: {
  'Content-Type': 'image/jpeg',
  'If-None-Match': '*',
},
body: file,
});

if (!response.ok) {
throw new Error(`Upload failed: ${response.status}`);
}

mutation completeMediaUpload(
$uploadToken: String!
$name: String!
$mediaLabelIds: [ID]
) {
completeMediaUpload(
  uploadToken: $uploadToken
  name: $name
  mediaLabelIds: $mediaLabelIds
) {
  success
  media {
    id
    name
    url
    mimeType
    size
  }
  errors {
    field
    code
    message
  }
}
}

{
"uploadToken": "b3f1c2a4-9d5e-4c7b-8a1f-2e6d0c9a7b12",
"name": "campaign-hero.jpg",
"mediaLabelIds": ["12"]
}

{
"data": {
  "completeMediaUpload": {
    "success": true,
    "media": {
      "id": "102",
      "name": "campaign-hero.jpg",
      "url": "https://cdn.example.com/5e6f7a8b/",
      "mimeType": "image/jpeg",
      "size": 2048576
    },
    "errors": []
  }
}
}

Scheduling a Post with the Uploaded Media

Both upload paths return the created media, including its id. Pass that id in the media list of any scheduling mutation to attach the file to a post:

mutation scheduleTweet($input: ScheduleTweetInput!) {
  scheduleTweet(input: $input) {
    success
    errors {
      field
      code
      message
    }
  }
}

{
  "input": {
    "username": "myhandle",
    "postAt": "2025-12-01T15:30:00Z",
    "thread": [
      {
        "text": "Our new campaign is live 🚀",
        "order": 0,
        "media": [{ "id": "1001" }]
      }
    ]
  }
}

{
  "data": {
    "scheduleTweet": {
      "success": true,
      "errors": []
    }
  }
}

You can also reference the file by the name you gave it when uploading, which is handy when you don't keep track of IDs:

{
  "media": [{ "name": "campaign-hero.jpg" }]
}

Names are matched case-insensitively and the first match wins, so prefer id when several files share a name.

Uploaded files stay in your Content Library, so the same id can be attached to as many posts as you like. Uploading is only needed once per file.

See Attaching Media for the full rules on media, including how many files each platform accepts.

Rate Limits

Media uploads count against a separate, stricter budget on top of the general API rate limit:

An upload counts against this budget when it begins, that is, on each uploadMediaFromUrl or startMediaUpload call.

When you exceed these limits, the mutation returns success: false with a Media upload rate limit exceeded error.

The two budgets are tracked separately, so exhausting your upload budget never blocks your regular API requests. They aren't mutually exclusive, though: like every API call, an upload mutation also counts against the general rate limit.

Error Handling

The mutations return success: false with details in errors when there's a failure.

Always check success and inspect errors before using the returned media.