> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ugc.inc/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Post Status

> Get the status of a specific post

## Endpoint

```
POST https://api.ugc.inc/post/status
```

## Overview

Check the current status of a specific post. Use this endpoint to monitor whether a post has been successfully published or if there were any issues.

## Post Status Values

* **`scheduled`** - Post is scheduled to be published at a future time
* **`pending`** - Post is currently being processed/published
* **`complete`** - Post was successfully published to the platform
* **`failed`** - Post failed to publish; see `fail_category` for why

## Failure Categories

When `status` is `failed`, `fail_category` explains why:

* **`device_error`** - The posting device was unavailable or did not respond
* **`network_error`** - The connection dropped while posting
* **`upload_interrupted`** - The upload started but could not be confirmed as finished
* **`account_issue`** - The social account was not in a usable state
* **`capacity_deferred`** - No posting capacity was available; the post will be retried
* **`platform_change`** - The social app's interface changed and the post could not complete
* **`unconfirmed`** - Posting finished but publication could not be confirmed
* **`unknown`** - The post failed for an unrecognized reason

## Request Body

<ParamField body="postId" type="string" required>
  Post ID to check status for
</ParamField>

## Response

<ResponseField name="data" type="object">
  Status information for the post

  <Expandable title="Response properties">
    <ResponseField name="post_id" type="string">
      ID of the post being checked
    </ResponseField>

    <ResponseField name="status" type="string">
      Current status of the post
    </ResponseField>

    <ResponseField name="fail_category" type="string | null">
      Why the post failed. Set when `status` is `failed`, otherwise `null`.
      One of `device_error`, `network_error`, `upload_interrupted`,
      `account_issue`, `capacity_deferred`, `platform_change`, `unconfirmed`,
      `unknown`.
    </ResponseField>

    <ResponseField name="postUrl" type="string | undefined">
      Direct URL to the post on the social media platform. Only available when status is `complete`.

      * **TikTok**: `https://www.tiktok.com/@username/video/{social_id}`
      * **Instagram**: `https://www.instagram.com/p/{social_id}/`
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.ugc.inc/post/status \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "postId": "post_abc123"
    }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.ugc.inc/post/status',
      headers={
          'Authorization': 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/json'
      },
      json={
          'postId': 'post_abc123'
      }
  )

  data = response.json()

  if data['ok']:
      print(f"Post status: {data['data']['status']}")
      
      if data['data']['status'] == 'complete':
          print('Post was successfully published!')
          if 'postUrl' in data['data']:
              print(f"View at: {data['data']['postUrl']}")
      elif data['data']['status'] == 'failed':
          print('Post failed to publish.')
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.ugc.inc/post/status', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      postId: 'post_abc123'
    })
  });

  const data = await response.json();

  if (data.ok) {
    console.log(`Post status: ${data.data.status}`);
    
    if (data.data.status === 'complete') {
      console.log('Post was successfully published!');
      if (data.data.postUrl) {
        console.log(`View at: ${data.data.postUrl}`);
      }
    } else if (data.data.status === 'failed') {
      console.log('Post failed to publish.');
    }
  }
  ```

  ```typescript React theme={null}
  import { UGCClient } from 'ugcinc';

  const client = new UGCClient({
    apiKey: 'YOUR_API_KEY'
  });

  const response = await client.posts.getStatus({
    postId: 'post_abc123'
  });

  if (response.ok) {
    console.log(`Post ${response.data.post_id}: ${response.data.status}`);
    
    switch (response.data.status) {
      case 'scheduled':
        console.log('Post is scheduled for later');
        break;
      case 'pending':
        console.log('Post is being published...');
        break;
      case 'complete':
        console.log('Post was successfully published!');
        if (response.data.postUrl) {
          console.log(`View at: ${response.data.postUrl}`);
        }
        break;
      case 'failed':
        console.log(`Post failed to publish: ${response.data.fail_category}`);
        break;
    }
  }
  ```
</RequestExample>

<ResponseExample>
  ```json Success Response (Complete - TikTok) theme={null}
  {
    "ok": true,
    "code": 200,
    "message": "Success",
    "data": {
      "post_id": "post_abc123",
      "status": "complete",
      "postUrl": "https://www.tiktok.com/@username/video/7234567890123456789"
    }
  }
  ```

  ```json Success Response (Complete - Instagram) theme={null}
  {
    "ok": true,
    "code": 200,
    "message": "Success",
    "data": {
      "post_id": "post_def456",
      "status": "complete",
      "postUrl": "https://www.instagram.com/p/ABC123xyz/"
    }
  }
  ```

  ```json Success Response (Pending) theme={null}
  {
    "ok": true,
    "code": 200,
    "message": "Success",
    "data": {
      "post_id": "post_abc123",
      "status": "pending"
    }
  }
  ```

  ```json Success Response (Scheduled) theme={null}
  {
    "ok": true,
    "code": 200,
    "message": "Success",
    "data": {
      "post_id": "post_abc123",
      "status": "scheduled"
    }
  }
  ```

  ```json Success Response (Failed) theme={null}
  {
    "ok": true,
    "code": 200,
    "message": "Success",
    "data": {
      "post_id": "post_abc123",
      "status": "failed",
      "fail_category": "capacity_deferred"
    }
  }
  ```

  ```json Error Response (Not Found) theme={null}
  {
    "ok": false,
    "code": 404,
    "message": "Post not found"
  }
  ```
</ResponseExample>