GET
/
api
/
v2
/
users
/
linkedin
LinkedIn Integration Status
curl --request GET \
  --url https://api.buena.ai/api/v2/users/linkedin \
  --header 'x-api-key: <api-key>'
{
  "userId": "65e0a32640a597f6a7f897ea",
  "success": true,
  "data": {
    "linkedInIntegration": {
      "connected": true,
      "profileUrl": "https://linkedin.com/in/yourprofile",
      "name": "Your Name",
      "connectionCount": 1247,
      "actionsToday": 12,
      "dailyLimit": 100,
      "lastActivity": "2024-01-20T14:30:00Z"
    },
    "hasProxy": true,
    "timezone": "America/New_York"
  }
}

LinkedIn Integration Status

Verify your LinkedIn integration status, connection details, and account information. This simplified endpoint automatically detects the user from the API key, eliminating the need for user IDs in the URL.

Requires a user-specific API key with users:read permission. Global API keys should use the legacy routes.

Request

x-api-key
string
required

Your user-specific API key with users:read permission (format: bna_hexstring)

Examples

Check LinkedIn Status

curl -X GET "https://api.buena.ai/api/v2/users/linkedin" \
  -H "x-api-key: bna_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Response

userId
string

The authenticated user’s ID

success
boolean

Always true for successful requests

data
object

LinkedIn integration information

{
  "userId": "65e0a32640a597f6a7f897ea",
  "success": true,
  "data": {
    "linkedInIntegration": {
      "connected": true,
      "profileUrl": "https://linkedin.com/in/yourprofile",
      "name": "Your Name",
      "connectionCount": 1247,
      "actionsToday": 12,
      "dailyLimit": 100,
      "lastActivity": "2024-01-20T14:30:00Z"
    },
    "hasProxy": true,
    "timezone": "America/New_York"
  }
}

Advanced Use Cases

1. Integration Health Check

async function checkLinkedInHealth() {
  try {
    const response = await fetch("https://api.buena.ai/api/v2/users/linkedin", {
      headers: {
        "x-api-key": process.env.BUENA_USER_API_KEY,
      },
    });

    const data = await response.json();
    const integration = data.data.linkedInIntegration;

    if (!integration.connected) {
      console.log("❌ LinkedIn not connected - setup required");
      return false;
    }

    // Check daily usage
    const usagePercentage =
      (integration.actionsToday / integration.dailyLimit) * 100;

    if (usagePercentage > 90) {
      console.log(
        "⚠️ High usage warning:",
        `${usagePercentage.toFixed(1)}% of daily limit used`
      );
    } else if (usagePercentage > 50) {
      console.log(
        "⚡ Moderate usage:",
        `${usagePercentage.toFixed(1)}% of daily limit used`
      );
    } else {
      console.log(
        "✅ Low usage:",
        `${usagePercentage.toFixed(1)}% of daily limit used`
      );
    }

    // Check for recent activity
    const lastActivity = new Date(integration.lastActivity);
    const hoursSinceActivity =
      (Date.now() - lastActivity.getTime()) / (1000 * 60 * 60);

    if (hoursSinceActivity > 24) {
      console.log("💤 No activity in 24+ hours - consider scheduling actions");
    } else {
      console.log("🟢 Recent activity detected");
    }

    return true;
  } catch (error) {
    console.error("Failed to check LinkedIn health:", error);
    return false;
  }
}

// Run health check
checkLinkedInHealth();

2. Usage Monitoring

import requests
import json
from datetime import datetime, timedelta

class LinkedInMonitor:
    def __init__(self, api_key):
        self.api_key = api_key
        self.base_url = 'https://api.buena.ai/api/v2'

    def get_status(self):
        """Get current LinkedIn integration status"""
        response = requests.get(
            f'{self.base_url}/users/linkedin',
            headers={'x-api-key': self.api_key}
        )
        return response.json()

    def get_usage_summary(self):
        """Get usage summary and recommendations"""
        status_data = self.get_status()
        integration = status_data['data']['linkedInIntegration']

        if not integration['connected']:
            return {
                'status': 'disconnected',
                'message': 'LinkedIn account not connected',
                'action': 'setup_required'
            }

        actions_today = integration['actionsToday']
        daily_limit = integration['dailyLimit']
        usage_percent = (actions_today / daily_limit) * 100

        # Calculate remaining capacity
        remaining_actions = daily_limit - actions_today

        summary = {
            'status': 'connected',
            'actions_today': actions_today,
            'daily_limit': daily_limit,
            'usage_percent': round(usage_percent, 1),
            'remaining_actions': remaining_actions,
            'connection_count': integration['connectionCount'],
            'last_activity': integration['lastActivity']
        }

        # Add recommendations
        if usage_percent >= 95:
            summary['recommendation'] = 'Daily limit nearly reached - pause automation'
            summary['priority'] = 'high'
        elif usage_percent >= 80:
            summary['recommendation'] = 'High usage - monitor closely'
            summary['priority'] = 'medium'
        elif usage_percent <= 20:
            summary['recommendation'] = 'Low usage - consider increasing automation'
            summary['priority'] = 'low'
        else:
            summary['recommendation'] = 'Usage within normal range'
            summary['priority'] = 'normal'

        return summary

    def check_inactivity(self, hours_threshold=12):
        """Check for extended periods of inactivity"""
        status_data = self.get_status()
        integration = status_data['data']['linkedInIntegration']

        if not integration['lastActivity']:
            return {
                'inactive': True,
                'message': 'No activity recorded',
                'hours_since': None
            }

        last_activity = datetime.fromisoformat(integration['lastActivity'].replace('Z', '+00:00'))
        hours_since = (datetime.now(last_activity.tzinfo) - last_activity).total_seconds() / 3600

        return {
            'inactive': hours_since > hours_threshold,
            'hours_since': round(hours_since, 1),
            'message': f'Last activity: {hours_since:.1f} hours ago'
        }

# Usage
monitor = LinkedInMonitor(os.getenv('BUENA_USER_API_KEY'))

# Get current usage summary
summary = monitor.get_usage_summary()
print(f"LinkedIn Usage: {summary['usage_percent']}%")
print(f"Recommendation: {summary['recommendation']}")

# Check for inactivity
inactivity = monitor.check_inactivity()
if inactivity['inactive']:
    print(f"⚠️ Inactive for {inactivity['hours_since']} hours")

Legacy Routes

For backward compatibility, these legacy routes are still supported but require explicit user IDs:

  • GET /api/v2/users/linkedin/user-linkedin-integration/:userId - Get LinkedIn integration for specific user
  • POST /api/v2/users/integrations/setup-linkedin-integration - Setup LinkedIn integration (legacy)

Error Responses

Global API Key Used (400)

{
  "error": "When using global API key, please use the specific route: /api/v2/users/linkedin/user-linkedin-integration/:userId",
  "availableRoute": "/api/v2/users/linkedin/user-linkedin-integration/:userId"
}

LinkedIn Not Connected (200)

{
  "userId": "65e0a32640a597f6a7f897ea",
  "success": true,
  "data": {
    "linkedInIntegration": {
      "connected": false,
      "setupUrl": "https://app.buena.ai/integrations/linkedin"
    },
    "hasProxy": false,
    "timezone": "America/New_York"
  }
}

Invalid Permission (403)

{
  "error": true,
  "code": "PERMISSION_DENIED",
  "message": "Insufficient permissions for user data access",
  "version": "2.0",
  "timestamp": "2024-01-20T15:30:00Z",
  "permissionHelp": {
    "required": "users:read",
    "available": ["linkedin:schedule"],
    "documentation": "https://docs.buena.ai/authentication"
  }
}

Next Steps