---
title: "Run Social Profile Analysis"
method: POST
path: "/v1/social-profile-analysis"
tags: ["social-profile-analysis"]
---

# Run Social Profile Analysis

`POST /v1/social-profile-analysis`

Create a Social Profile Analysis job for known social profile URLs. The base Match layer returns matched records; optional Behavioral Analysis adds interpretation over those matched records. When `responseMode` is `sync`, the API waits for an inline result until the configured timeout. Every response includes `X-Job-Id`.

## Request body

- SocialProfileAnalysisRunRequest — Run endpoint payload for Social Profile Analysis.
  - `analysisTypes` AnalysisType[]
  - `behavioralAnalysis` BehavioralAnalysisConfig — Optional interpretation layer that uses Match output as input.
    - `enabled` boolean
    - `focus` string[]
    - `targetContext` TargetContext
      - `description` string, nullable
      - `name` string, required
      - `type` 'person' | 'organization' | 'school' | 'company' | 'public_figure' | 'event' | 'location' | 'institution' | 'other'
    - `timeBucket` 'day' | 'week' | 'month'
  - `match` SocialProfileAnalysisMatchConfig, required — Base Match configuration for selecting relevant records.
    - `confidenceThreshold` number
    - `criteria` string[]
    - `customPrompt` string, nullable
    - `dataTypes` SocialDataType[]
    - `maxRecords` integer
    - `timeRange` SocialAnalysisTimeRange
      - `end` string, nullable
      - `start` string, nullable
  - `responseMode` 'sync' | 'async'
  - `subject` SocialProfileAnalysisSubject, required — Known profile subject for social profile analysis.
    - `name` string, required
    - `socialMediaUrls` string[]

## Response `200`

Matched social records and optional behavioral analysis when completed inline, otherwise a job envelope.

- union
  - SocialProfileAnalysisResult — Inline or final Social Profile Analysis result payload.
    - `analysisTypes` AnalysisType[]
    - `behavioralAnalysis` BehavioralAnalysisResult
      - `accountsDrivingActivity` string[]
      - `confidence` number
      - `explanation` string, nullable
      - `keyRecordIds` string[]
      - `keySignals` string[]
      - `limits` string[]
      - `riskAssessment` RiskAssessment, required
        - `confidence` number
        - `level` 'none' | 'low' | 'medium' | 'high' | 'unknown'
        - `rationale` string, required
      - `summary` string, required
      - `timeline` BehavioralTimelineItem[]
        - `period` string, required
        - `recordIds` string[]
        - `summary` string, required
    - `capability` 'social_profile_analysis'
    - `items` SocialMatchedRecord[]
      - `confidence` number, required
      - `confidenceCategory` 'likely' | 'uncertain', required
      - `evidenceExcerpt` string, required
      - `id` string, required
      - `label` string, required
      - `matchRationale` string[]
      - `matchedCriteria` string[]
      - `matchedInputs` MatchedInputReference[]
        - `inputType` 'name' | 'alias' | 'adverse_term' | 'keyword' | 'region' | 'email' | 'phone' | 'address' | 'username' | 'domain' | 'location' | 'employer' | 'social_url' | 'seed_url' | 'date_of_birth' | 'place_of_birth' | 'age' | 'gender' | 'drivers_license_state' | 'employment_role' | 'employment_department' | 'employment_location' | 'employment_status', required
        - `value` string, required
      - `normalizedAttributes` SanitizedNormalizedAttributes — Sanitized, connector-agnostic normalized attributes.
        - `addresses` string[]
        - `dates` string[]
        - `domains` string[]
        - `emails` string[]
        - `keywords` string[]
        - `locations` string[]
        - `names` string[]
        - `organizations` string[]
        - `phones` string[]
        - `profileHandles` string[]
        - `usernames` string[]
      - `platform` 'x' | 'instagram' | 'telegram' | 'youtube' | 'facebook', required
      - `publishedAt` string, date-time, nullable
      - `reasonForMatch` string, required
      - `safeMetadata` object
      - `sourceProfileUrl` string, required
      - `sourceRecord` object
      - `summary` string, required
      - `text` string, nullable
      - `type` 'post' | 'comment' | 'media' | 'link' | 'profile_field' | 'relationship' | 'video', required
    - `limit` integer
    - `match` MatchAnalysisResult, required
      - `matchedRecords` SocialMatchedRecord[]
        - `confidence` number, required
        - `confidenceCategory` 'likely' | 'uncertain', required
        - `evidenceExcerpt` string, required
        - `id` string, required
        - `label` string, required
        - `matchRationale` string[]
        - `matchedCriteria` string[]
        - `matchedInputs` MatchedInputReference[]
          - `inputType` 'name' | 'alias' | 'adverse_term' | 'keyword' | 'region' | 'email' | 'phone' | 'address' | 'username' | 'domain' | 'location' | 'employer' | 'social_url' | 'seed_url' | 'date_of_birth' | 'place_of_birth' | 'age' | 'gender' | 'drivers_license_state' | 'employment_role' | 'employment_department' | 'employment_location' | 'employment_status', required
          - `value` string, required
        - `normalizedAttributes` SanitizedNormalizedAttributes — Sanitized, connector-agnostic normalized attributes.
          - `addresses` string[]
          - `dates` string[]
          - `domains` string[]
          - `emails` string[]
          - `keywords` string[]
          - `locations` string[]
          - `names` string[]
          - `organizations` string[]
          - `phones` string[]
          - `profileHandles` string[]
          - `usernames` string[]
        - `platform` 'x' | 'instagram' | 'telegram' | 'youtube' | 'facebook', required
        - `publishedAt` string, date-time, nullable
        - `reasonForMatch` string, required
        - `safeMetadata` object
        - `sourceProfileUrl` string, required
        - `sourceRecord` object
        - `summary` string, required
        - `text` string, nullable
        - `type` 'post' | 'comment' | 'media' | 'link' | 'profile_field' | 'relationship' | 'video', required
      - `summary` string, required
    - `nextCursor` string, nullable
    - `subject` SocialProfileAnalysisSubject, required — Known profile subject for social profile analysis.
      - `name` string, required
      - `socialMediaUrls` string[]
    - `total` integer, nullable
    - `warnings` ApiWarning[]
      - `code` string, required
      - `message` string, required
    - `workflowType` 'social_profile_analysis'
  - JobEnvelopeSocialProfileAnalysisResult
    - `capability` 'web_search' | 'pii_expansion' | 'social_profile_analysis', required
    - `completedAt` string, date-time, nullable
    - `error` ApiError — Standard API error payload.
      - `code` string, required
      - `message` string, required
      - `retryable` boolean
    - `expiresAt` string, date-time, nullable
    - `jobId` string, required
    - `progress` JobProgress — Progress metadata for long-running jobs.
      - `completedSteps` integer
      - `message` string, nullable
      - `stage` string, required
      - `totalSteps` integer, nullable
    - `result` SocialProfileAnalysisResult — Inline or final Social Profile Analysis result payload.
      - `analysisTypes` AnalysisType[]
      - `behavioralAnalysis` BehavioralAnalysisResult
        - `accountsDrivingActivity` string[]
        - `confidence` number
        - `explanation` string, nullable
        - `keyRecordIds` string[]
        - `keySignals` string[]
        - `limits` string[]
        - `riskAssessment` RiskAssessment, required
          - `confidence` number
          - `level` 'none' | 'low' | 'medium' | 'high' | 'unknown'
          - `rationale` string, required
        - `summary` string, required
        - `timeline` BehavioralTimelineItem[]
          - `period` string, required
          - `recordIds` string[]
          - `summary` string, required
      - `capability` 'social_profile_analysis'
      - `items` SocialMatchedRecord[]
        - `confidence` number, required
        - `confidenceCategory` 'likely' | 'uncertain', required
        - `evidenceExcerpt` string, required
        - `id` string, required
        - `label` string, required
        - `matchRationale` string[]
        - `matchedCriteria` string[]
        - `matchedInputs` MatchedInputReference[]
          - `inputType` 'name' | 'alias' | 'adverse_term' | 'keyword' | 'region' | 'email' | 'phone' | 'address' | 'username' | 'domain' | 'location' | 'employer' | 'social_url' | 'seed_url' | 'date_of_birth' | 'place_of_birth' | 'age' | 'gender' | 'drivers_license_state' | 'employment_role' | 'employment_department' | 'employment_location' | 'employment_status', required
          - `value` string, required
        - `normalizedAttributes` SanitizedNormalizedAttributes — Sanitized, connector-agnostic normalized attributes.
          - `addresses` string[]
          - `dates` string[]
          - `domains` string[]
          - `emails` string[]
          - `keywords` string[]
          - `locations` string[]
          - `names` string[]
          - `organizations` string[]
          - `phones` string[]
          - `profileHandles` string[]
          - `usernames` string[]
        - `platform` 'x' | 'instagram' | 'telegram' | 'youtube' | 'facebook', required
        - `publishedAt` string, date-time, nullable
        - `reasonForMatch` string, required
        - `safeMetadata` object
        - `sourceProfileUrl` string, required
        - `sourceRecord` object
        - `summary` string, required
        - `text` string, nullable
        - `type` 'post' | 'comment' | 'media' | 'link' | 'profile_field' | 'relationship' | 'video', required
      - `limit` integer
      - `match` MatchAnalysisResult, required
        - `matchedRecords` SocialMatchedRecord[]
          - `confidence` number, required
          - `confidenceCategory` 'likely' | 'uncertain', required
          - `evidenceExcerpt` string, required
          - `id` string, required
          - `label` string, required
          - `matchRationale` string[]
          - `matchedCriteria` string[]
          - `matchedInputs` MatchedInputReference[]
            - `inputType` 'name' | 'alias' | 'adverse_term' | 'keyword' | 'region' | 'email' | 'phone' | 'address' | 'username' | 'domain' | 'location' | 'employer' | 'social_url' | 'seed_url' | 'date_of_birth' | 'place_of_birth' | 'age' | 'gender' | 'drivers_license_state' | 'employment_role' | 'employment_department' | 'employment_location' | 'employment_status', required
            - `value` string, required
          - `normalizedAttributes` SanitizedNormalizedAttributes — Sanitized, connector-agnostic normalized attributes.
            - `addresses` string[]
            - `dates` string[]
            - `domains` string[]
            - `emails` string[]
            - `keywords` string[]
            - `locations` string[]
            - `names` string[]
            - `organizations` string[]
            - `phones` string[]
            - `profileHandles` string[]
            - `usernames` string[]
          - `platform` 'x' | 'instagram' | 'telegram' | 'youtube' | 'facebook', required
          - `publishedAt` string, date-time, nullable
          - `reasonForMatch` string, required
          - `safeMetadata` object
          - `sourceProfileUrl` string, required
          - `sourceRecord` object
          - `summary` string, required
          - `text` string, nullable
          - `type` 'post' | 'comment' | 'media' | 'link' | 'profile_field' | 'relationship' | 'video', required
        - `summary` string, required
      - `nextCursor` string, nullable
      - `subject` SocialProfileAnalysisSubject, required — Known profile subject for social profile analysis.
        - `name` string, required
        - `socialMediaUrls` string[]
      - `total` integer, nullable
      - `warnings` ApiWarning[]
        - `code` string, required
        - `message` string, required
      - `workflowType` 'social_profile_analysis'
    - `resultUrl` string, nullable
    - `startedAt` string, date-time, nullable
    - `status` 'queued' | 'running' | 'completed' | 'failed' | 'expired', required
    - `streamUrl` string, nullable
    - `submittedAt` string, date-time, required
    - `summary` JobSummary — Summary counters for a completed or running job.
      - `itemsFound` integer
      - `itemsReturned` integer
    - `warnings` ApiWarning[]
      - `code` string, required
      - `message` string, required

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/intraceai/apis/intelligence-api.md) · [All operations](https://skmtc.net/intraceai/apis/intelligence-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/intraceai/intelligence-api/revisions/c0216eef7380/schema)