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

# Get Integration Details

> Get details and health status of a connected social platform

<Note>
  **Try it out!** Use the API playground on the right to test the Get Integration Details endpoint directly.
</Note>

## Overview

Get detailed information about a specific connected social platform, including account details and connection health status. Use this to:

* Verify if a connection is still valid before scheduling
* Check if tokens have expired and need re-authentication
* Get account details for display purposes

<Info>
  If the health status shows `expired` or `error`, the user needs to reconnect the account through the [Hooked Dashboard](https://hooked.so/settings/integrations).
</Info>

***

## Endpoint

```
GET /v1/integration/{integrationId}
```

***

## Path Parameters

<ParamField path="integrationId" type="string" required>
  The unique ID of the integration to retrieve
</ParamField>

***

## Headers

<ParamField header="x-api-key" type="string" required>
  Your API key from [API Settings](https://hooked.so/settings/api)
</ParamField>

***

## Response

<ResponseField name="success" type="boolean">
  Whether the request was successful
</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="Integration Object">
    <ResponseField name="id" type="string">
      Unique integration ID
    </ResponseField>

    <ResponseField name="type" type="string">
      Platform type: `youtube`, `tiktok`, or `instagram`
    </ResponseField>

    <ResponseField name="identifier" type="string">
      Platform-specific identifier (channel ID, username, etc.)
    </ResponseField>

    <ResponseField name="account" type="object">
      Connected account information

      <Expandable title="Account Object">
        <ResponseField name="id" type="string">
          Platform account ID
        </ResponseField>

        <ResponseField name="name" type="string">
          Display name of the account
        </ResponseField>

        <ResponseField name="username" type="string">
          Username or handle
        </ResponseField>

        <ResponseField name="avatarUrl" type="string">
          Profile picture URL
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="health" type="object">
      Connection health status

      <Expandable title="Health Object">
        <ResponseField name="status" type="string">
          Health status:

          * `healthy` - Connection is working properly
          * `expired` - Token has expired, needs reconnection
          * `error` - Connection error, needs reconnection
        </ResponseField>

        <ResponseField name="tokenValid" type="boolean">
          Whether the access token is still valid
        </ResponseField>

        <ResponseField name="lastChecked" type="string">
          ISO 8601 timestamp of when health was checked
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      When the integration was connected
    </ResponseField>
  </Expandable>
</ResponseField>

***

## Request Example

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://api.hooked.so/v1/integration/int_yt_abc123" \
    -H "x-api-key: your_api_key_here"
  ```

  ```javascript Node.js theme={null}
  const integrationId = 'int_yt_abc123';

  const response = await fetch(`https://api.hooked.so/v1/integration/${integrationId}`, {
    method: 'GET',
    headers: {
      'x-api-key': process.env.HOOKED_API_KEY
    }
  });

  const data = await response.json();

  if (data.data.health.status !== 'healthy') {
    console.log('Integration needs reconnection!');
  } else {
    console.log('Integration is healthy');
  }
  ```

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

  integration_id = 'int_yt_abc123'

  response = requests.get(
      f'https://api.hooked.so/v1/integration/{integration_id}',
      headers={'x-api-key': 'your_api_key_here'}
  )

  data = response.json()
  health = data['data']['health']

  if health['status'] != 'healthy':
      print(f"Integration needs reconnection: {health['status']}")
  else:
      print("Integration is healthy")
  ```
</RequestExample>

***

## Response Examples

<ResponseExample>
  ```json Healthy Integration theme={null}
  {
    "success": true,
    "data": {
      "id": "int_yt_abc123",
      "type": "youtube",
      "identifier": "UC1234567890",
      "account": {
        "id": "UC1234567890",
        "name": "My YouTube Channel",
        "username": "mychannel",
        "avatarUrl": "https://yt3.ggpht.com/..."
      },
      "health": {
        "status": "healthy",
        "tokenValid": true,
        "lastChecked": "2024-03-15T10:00:00.000Z"
      },
      "createdAt": "2024-01-15T08:30:00.000Z"
    }
  }
  ```

  ```json Expired Token theme={null}
  {
    "success": true,
    "data": {
      "id": "int_tt_xyz789",
      "type": "tiktok",
      "identifier": "@myaccount",
      "account": {
        "id": "6912345678901234567",
        "name": "My TikTok",
        "username": "myaccount",
        "avatarUrl": "https://p16-sign.tiktokcdn.com/..."
      },
      "health": {
        "status": "expired",
        "tokenValid": false,
        "lastChecked": "2024-03-15T10:00:00.000Z"
      },
      "createdAt": "2024-01-10T12:00:00.000Z"
    }
  }
  ```

  ```json Error - Not Found theme={null}
  {
    "code": "not_found",
    "message": "Integration not found",
    "details": {
      "resource_id": "int_invalid",
      "resource_type": "Integration"
    }
  }
  ```
</ResponseExample>

***

## Health Status Values

| Status    | Description                           | Action Required                  |
| --------- | ------------------------------------- | -------------------------------- |
| `healthy` | Connection is working, token is valid | None                             |
| `expired` | Access token has expired              | User must reconnect in dashboard |
| `error`   | Connection error or missing token     | User must reconnect in dashboard |

***

## Checking Health Before Scheduling

It's a good practice to check integration health before scheduling a video:

```javascript theme={null}
async function scheduleIfHealthy(videoId, integrationId, scheduledDateTime) {
  // Check health first
  const healthResponse = await fetch(
    `https://api.hooked.so/v1/integration/${integrationId}`,
    { headers: { 'x-api-key': process.env.HOOKED_API_KEY } }
  );

  const { data: integration } = await healthResponse.json();

  if (integration.health.status !== 'healthy') {
    throw new Error(`Integration ${integration.type} needs reconnection`);
  }

  // Proceed with scheduling
  const scheduleResponse = await fetch(
    'https://api.hooked.so/v1/schedule/create',
    {
      method: 'POST',
      headers: {
        'x-api-key': process.env.HOOKED_API_KEY,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ videoId, integrationId, scheduledDateTime })
    }
  );

  return await scheduleResponse.json();
}
```

***

## Next Steps

<CardGroup cols={2}>
  <Card title="List Integrations" icon="list" href="/api-reference/integration/list">
    View all connected platforms
  </Card>

  <Card title="Disconnect" icon="plug" href="/api-reference/integration/disconnect">
    Remove a connected account
  </Card>

  <Card title="Schedule Video" icon="calendar" href="/api-reference/schedule/create">
    Schedule a video for publishing
  </Card>

  <Card title="Dashboard" icon="gear" href="https://hooked.so/settings/integrations">
    Reconnect accounts in dashboard
  </Card>
</CardGroup>


## OpenAPI

````yaml GET /v1/integration/{integrationId}
openapi: 3.0.0
info:
  title: Hooked API
  version: 1.0.0
  description: AI Video Generation API
servers:
  - url: https://api.hooked.so
security:
  - ApiKeyAuth: []
paths:
  /v1/integration/{integrationId}:
    get:
      tags:
        - Integrations
      summary: Get Integration Details
      description: Get details and health status of a connected social platform
      operationId: getIntegrationDetails
      parameters:
        - name: integrationId
          in: path
          description: Integration ID
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                      type:
                        type: string
                        enum:
                          - youtube
                          - tiktok
                          - instagram
                      identifier:
                        type: string
                      account:
                        type: object
                        properties:
                          id:
                            type: string
                          name:
                            type: string
                          username:
                            type: string
                          avatarUrl:
                            type: string
                      health:
                        type: object
                        properties:
                          status:
                            type: string
                            enum:
                              - healthy
                              - expired
                              - error
                          tokenValid:
                            type: boolean
                          lastChecked:
                            type: string
                            format: date-time
                      createdAt:
                        type: string
                        format: date-time
      security:
        - ApiKeyAuth: []
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````