CreatorIQ Social Account APIs
Look up social accounts and posts by link or handle across Instagram, TikTok and YouTube, retrieve account history and Instagram stories history.
OpenAPI Specification
openapi: 3.0.1
info:
version: 1.0.0
title: CreatorIQ Social Account APIs
description: |
CreatorIQ CRM APIs for Social Account resource
### Changelog
#### 2025-02-27
#### Added
- new value `savedThumbnail` for YouTube video item for endpoint:
GET [https://apis.creatoriq.com/crm/v1/api/social/postInfo YouTube video only](https://creatoriq.stoplight.io/docs/ciq-api-documentation/f575c27239d31-get-social-post-info)
#### 2025-01-22
#### Added
- Added new value `pnkHash` for social post item for endpoints:
- [GET https://apis.creatoriq.com/crm/v1/api/social/postInfo](https://creatoriq.stoplight.io/docs/ciq-api-documentation/f575c27239d31-get-social-post-info)
- [GET https://apis.creatoriq.com/crm/v1/api/account/instagram/{id}/storiesHistory](https://creatoriq.stoplight.io/docs/ciq-api-documentation/d83baf3f82db6-get-stories-history)
termsOfService: 'https://www.creatoriq.com/legal/terms-of-use'
contact:
name: CreatorIQ
url: 'https://www.creatoriq.com'
email: support@creatoriq.com
license:
url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
name: Apache 2.0
servers:
- url: 'https://apis.creatoriq.com'
description: Live
paths:
'/crm/v1/api/account/instagram/{id}/storiesHistory':
get:
tags:
- Social
summary: Get stories history
description: |
## Fetch stories history for Instagram social account
The endpoint returns the entire history starting from the moment when the creator's social account was linked
and story monitoring was enabled.
For example, the curl below (without parameters) will return the entire Instagram stories history:
```
curl -X GET --location "https://apis.creatoriq.com/crm/v1/api/account/instagram/changedtokrakow/storiesHistory" \
-H "X-API-KEY: apikey" \
-H "Content-Type: application/json"
```
However, if we want to retrieve stories for a
specific period (in days), we set the exact dates of the period using the parameters ```from``` and ```to```. The format of
the ```from``` and ```to``` fields is ```YYYY-MM-DD```. The maximum number of entities obtained per request can be regulated by
the ```size``` parameter.
For example:
```
curl -X GET --location "https://apis.creatoriq.com/crm/v1/api/account/instagram/changedtokrakow/storiesHistory?from=2022-06-20&to=2022-06-23&size=2" \
-H "X-API-KEY: apikey" \
-H "Content-Type: application/json"
```
operationId: getInstagramStoriesHistory
parameters:
- name: from
in: query
description: From what date fetch stories
required: false
schema:
type: string
format: date
example: '2022-09-13'
examples:
default:
value: '2022-09-13'
- name: size
in: query
description: Count of fetched
required: false
schema:
type: integer
example: 20
examples:
default:
value: 20
- name: to
in: query
description: From date fetch
required: false
schema:
type: string
format: date
example: '2022-09-13'
examples:
default:
value: '2022-09-13'
- name: id
in: path
description: Instagram unique Identifier or username
required: true
schema:
type: string
pattern: '^[a-zA-Z0-9_\.]+$'
example: melrosehealth
examples:
default:
value: melrosehealth
responses:
'200':
$ref: '#/components/responses/InstagramAccountStoriesSuccessResponse'
'400':
$ref: '#/components/responses/ErrorResponse400'
'404':
$ref: '#/components/responses/ErrorResponse404'
security:
- apiKey: []
servers:
- url: 'https://apis.creatoriq.com'
description: Live
/crm/v1/api/social/accountInfo:
get:
tags:
- Social
summary: Get social account data
description: |
Returns information about a specific social account using either a social account url or a combination of the social network and username. <br/>
Allowed social networks: tiktok, instagram, twitch, youtube, facebook.
operationId: getSocialAccountData
parameters:
- name: source
in: query
description: Account data source (can be 'link' or 'user')
required: true
schema:
type: string
enum:
- link
- user
example: link
examples:
default:
value: link
- name: link
in: query
description: link to user social media account. Required if `source=link`
required: false
schema:
type: string
example: 'https:\\www.tiktok.com\@therock'
examples:
default:
value: 'https:\\www.tiktok.com\@therock'
- name: network
in: query
description: Name os social network. Required if `source=user`
required: false
schema:
type: string
enum:
- tiktok
- instagram
- twitch
- youtube
- facebook
example: youtube
examples:
default:
value: youtube
- name: user
in: query
description: Username or user id on social media. Requred if `source=user`
required: false
schema:
type: string
example: therock
examples:
default:
value: therock
responses:
'200':
description: One of possible responses.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/InstagramAccountInfoModel'
- $ref: '#/components/schemas/YoutubeAccountInfoModel'
- $ref: '#/components/schemas/FacebookAccountInfoModel'
- $ref: '#/components/schemas/TiktokAccountInfoModel'
'404':
$ref: '#/components/responses/ErrorResponse404'
security:
- apiKey: []
servers:
- url: 'https://apis.creatoriq.com'
description: Live
/crm/v1/api/social/postInfo:
get:
tags:
- Social
summary: Get Social PostInfo
description: Returns information about a specific social media post
operationId: getSocialPostInfo
parameters:
- name: link
in: query
description: Url to specific social network post
required: true
schema:
type: string
example: 'https://www.instagram.com/p/Cm-qszQrIla'
examples:
default:
value: 'https://www.instagram.com/p/Cm-qszQrIla'
- name: publisherId
in: query
description: Unique publisher id. Required if `checkAccounts=1`
required: false
schema:
type: integer
example: 841602
examples:
default:
value: 841602
- name: checkAccounts
in: query
description: Check if account exists in database
required: false
schema:
type: integer
enum:
- 0
- 1
example: 0
examples:
default:
value: 0
responses:
'200':
description: One of possible responses
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/InstagramPostModel'
- $ref: '#/components/schemas/FacebookPostModel'
- $ref: '#/components/schemas/LinkedinPostModel'
- $ref: '#/components/schemas/PinterestPostModel'
- $ref: '#/components/schemas/SnapchatPostModel'
- $ref: '#/components/schemas/TiktokPostModel'
- $ref: '#/components/schemas/TwitchPostModel'
- $ref: '#/components/schemas/TwitterPostModel'
- $ref: '#/components/schemas/WebPostModel'
- $ref: '#/components/schemas/YoutubePostModel'
'404':
$ref: '#/components/responses/ErrorResponse404'
security:
- apiKey: []
servers:
- url: 'https://apis.creatoriq.com'
description: Live
/crm/v1/api/accounts/lookup:
get:
tags:
- Social
summary: Search user in social network or in the CreatorIQ database
description: Search Creator by Social handle within your CRM
operationId: getUserInSocialNetwork
parameters:
- name: network
in: query
description: Name of social network.
required: true
schema:
type: string
enum:
- tiktok
- twitter
- pinterest
- instagram
- youtube
- twitch
- facebook
example: youtube
examples:
default:
value: youtube
- name: search
in: query
description: Search string or username or link to social account
required: true
schema:
type: string
example: therock
examples:
default:
value: therock
responses:
'200':
$ref: '#/components/responses/LookupSuccessResponse'
'400':
$ref: '#/components/responses/ErrorResponse400'
'404':
$ref: '#/components/responses/ErrorResponse404'
security:
- apiKey: []
servers:
- url: 'https://apis.creatoriq.com'
description: Live
'/crm/v1/api/{network}/account/{socialNetworkId}/history':
get:
tags:
- Social
summary: Get social account history
description: |
### Get social account history
This endpoint returns the subscription and viewing history of a social account for the period that we set in
the parameters. The period can be set in days or months using the parameter ```period=month``` or ```period=day```.
However, the endpoint will not return the account history for 12 months if the database only stores history
for 6 months.
If the period field is set to ```period=day```, the endpoint will return the history of changes in
views or subscriptions for the dates when the CreatorIQ cron recorded changes in the number of views or
subscribers. For example, if the account had 4 subscribers and 0 views on September 1, 2022, and the
account was added to CreatorIQ on the same day - September 1, 2022, and 49 views were added on October 1, 2022,
the output will be:
```
{
"SocialHistory":[
{
"Date":"2022-10-01 00:00:00",
"Subscribers":"4",
"Views":"49"
},
{
"Date":"2022-09-01 00:00:00",
"Subscribers":"4",
"Views":"0"
}
],
"href":"https://apis.creatoriq.com/crm/v1/api/youtube/account/UCJ80aAk5PcrD_bEYscCRkpQ/history?period=day&size=2",
"type":"SocialHistory"
}
```
As we can see, the data is returned starting from the oldest date.
Input curl was:
```
curl -X GET --location "https://apis.creatoriq.com/crm/v1/api/youtube/account/UCJ80aAk5PcrD_bEYscCRkpQ/history?period=day&size=2" \
-H "X-API-KEY: apikey" \
-H "Content-Type: application/json"
```
If ```period=month```, the history of changes in the number of subscribers or views of the social account is returned
by months. For example:
```
{
"SocialHistory":[
{
"Month":"December 2022",
"Subscribers":"2050000",
"Views":228074626
},
{
"Month":"January 2023",
"Subscribers":"2770000",
"Views":214931823.33333
},
{
"Month":"February 2023",
"Subscribers":"2993334",
"Views":81111695.5
}
],
"href":"https://apis.creatoriq.com/crm/v1/api/youtube/account/UCd84KUlhKQYXrMHsOPfyxcw/history?period=month&size=40",
"type":"SocialHistory"
}
```
The data is returned starting from the most recent date.
Input curl was:
```
curl -X GET --location "https://apis.creatoriq.com/crm/v1/api/youtube/account/UCd84KUlhKQYXrMHsOPfyxcw/history?period=month&size=40" \
-H "X-API-KEY: apikey" \
-H "Content-Type: application/json"
```
Using the ```size``` parameter, we can regulate the maximum number of entities in the response.
operationId: getSocialAccountHistory
parameters:
- name: period
in: query
description: Period which history fetch
required: false
schema:
type: string
enum:
- month
- day
default: day
example: month
examples:
default:
value: month
- name: size
in: query
description: Count
required: false
schema:
type: integer
minimum: 0
example: 6
examples:
default:
value: 6
- name: network
in: path
description: Social network
required: true
schema:
type: string
enum:
- youtube
- twitch
- instagram
- facebook
- twitter
- pinterest
example: facebook
examples:
default:
value: facebook
- name: socialNetworkId
in: path
description: |
Unique id of account from network. Can be fetched from [GET] '/crm/v1/api/publisher/{publisherId}/accounts' endpoint.
Field in response **SocialNetworkId**
required: true
schema:
type: string
example: '2094200507'
examples:
default:
value: '2094200507'
responses:
'200':
$ref: '#/components/responses/socialHistory'
'400':
$ref: '#/components/responses/ErrorResponse400'
security:
- apiKey: []
servers:
- url: 'https://apis.creatoriq.com'
description: Live
tags:
- name: Social
description: Public social API
components:
securitySchemes:
apiKey:
type: apiKey
name: x-api-key
in: header
responses:
ErrorResponse400:
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseModel'
ErrorResponse404:
description: Not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseModel'
LookupSuccessResponse:
description: Return lookup account data
content:
application/json:
schema:
$ref: '#/components/schemas/LookupSuccessResponseModel'
InstagramAccountStoriesSuccessResponse:
description: Return Instagram account post collection
content:
application/json:
schema:
$ref: '#/components/schemas/InstagramAccountStoriesSuccessResponseModel'
InstagramAccountTimelineSuccessResponse:
description: Return Instagram account post collection
content:
application/json:
schema:
$ref: '#/components/schemas/InstagramAccountTimelineSuccessResponseModel'
YoutubeAccountTimelineSuccessResponse:
description: Return YouTube account post collection
content:
application/json:
schema:
$ref: '#/components/schemas/YoutubeAccountTimelineSuccessResponseModel'
FacebookAccountTimelineSuccessResponse:
description: Return Facebook account post collection
content:
application/json:
schema:
$ref: '#/components/schemas/FacebookAccountTimelineSuccessResponseModel'
TiktokAccountTimelineSuccessResponse:
description: Return TikTok account post collection
content:
application/json:
schema:
$ref: '#/components/schemas/TiktokAccountTimelineSuccessResponseModel'
PinterestAccountTimelineSuccessResponse:
description: Return Pinterest account post collection
content:
application/json:
schema:
$ref: '#/components/schemas/PinterestAccountTimelineSuccessResponseModel'
TwitchAccountTimelineSuccessResponse:
description: Return Twitch account post collection
content:
application/json:
schema:
$ref: '#/components/schemas/TwitchAccountTimelineSuccessResponseModel'
TwitterAccountTimelineSuccessResponse:
description: Return Twitter account post collection
content:
application/json:
schema:
$ref: '#/components/schemas/TwitterAccountTimelineSuccessResponseModel'
SnapchatAccountTimelineSuccessResponse:
description: Return Snapchat account post collection
content:
application/json:
schema:
$ref: '#/components/schemas/SnapchatAccountTimelineSuccessResponseModel'
socialHistory:
description: Social history response
content:
application/json:
schema:
$ref: '#/components/schemas/socialHistoryResponseModel'
schemas:
InstagramAccountInfoModel:
type: object
properties:
type:
type: string
description: Type of Search
example: InstagramAccount
href:
type: string
description: CreatorIQ API URL to get creator's instagram account
format: URI
example: 'https://apis.creatoriq.com/crm/v1/api/account/instagram/account/therock'
InstagramAccount:
$ref: '#/components/schemas/InstagramAccountModel'
required:
- type
- href
- InstagramAccount
InstagramAccountModel:
type: object
properties:
id:
type: integer
description: Unique instagram account id
example: 18428653
url:
type: string
description: Instagram account url
format: URI
example: 'https://instagram.com/therock'
name:
type: string
description: Instagam account username
example: therock
profileImageUrl:
type: string
description: Url to profile image
format: URI
example: 'https:\\scontent-sea1-1.xx.fbcdn.net\v\t51.2885-15\314397231_636674618202803_1672434101401302981_n.jpg?_nc_cat=1&ccb=1-7&_nc_sid=86c713&_nc_ohc=iiq9WDog-BkAX-0fEDs&_nc_ht=scontent-sea1-1.xx&edm=AL-3X8kEAAAA&oh=00_AfAKZgC1wAOCZXrs0ocIY-MHoehwyqpA7IBbtpzDn6sgeA&oe=63BDBD13'
posts:
type: integer
description: Count of post on account
example: 5767
followers:
type: integer
description: Count of followers on account
example: 5767339728669
likes:
type: integer
description: Count of likes
example: 0
bio:
type: string
description: Account bio information
example: The best instagram account
avgLikes:
type: integer
example: 0
avgLikes10:
type: integer
example: 0
comments:
type: integer
example: 0
avgComments:
type: integer
example: 0
avgComments10:
type: integer
example: 0
timeline:
type: object
properties:
type:
type: string
description: Type of Search
example: SocialPostsCollection
href:
type: string
description: CreatorIQ API URL to get creator's instagram stories
format: URI
example: ''
x-deprecated: true
insights:
type: object
nullable: true
properties:
impressions:
type: integer
description: Impressions count
example: 1
reach:
type: integer
description: Number of users who have seen the post
example: 1
type:
type: string
description: Impression type
example: ''
exits:
type: string
description: Impressions Exits
example: ''
replies:
type: integer
description: Impressions Replies
example: 1
tapsForward:
type: integer
description: Taps Forward
example: 1
tapsBack:
type: integer
description: Taps Back
example: 1
required:
- impressions
- reach
default: null
videoStatistics:
type: string
nullable: true
example: ''
verified:
type: string
nullable: true
example: ''
required:
- id
- url
YoutubeAccountInfoModel:
type: object
properties:
type:
type: string
description: Type of Search
example: YoutubeAccount
href:
type: string
description: CreatorIQ API URL to get creator's Youtube account
format: URI
example: 'https://apis.creatoriq.com/crm/v1/api/account/youtube/account/UCeNhHgTE36tTQkJsjPaPwnA'
YoutubeAccount:
$ref: '#/components/schemas/YoutubeAccountModel'
required:
- type
- href
- YoutubeAccount
YoutubeAccountModel:
type: object
properties:
id:
type: string
description: Unique Youtube account id
example: UCeNhHgTE36tTQkJsjPaPwnA
url:
type: string
description: Youtube account url
format: URI
example: 'https:\\youtube.com\channel\UCeNhHgTE36tTQkJsjPaPwnA'
channelName:
type: string
description: Youtube channel name
example: UCeNhHgTE36tTQkJsjPaPwnA
logoUrl:
type: string
description: Url to Youtube account logo
format: URI
example: 'https:\\yt3.ggpht.com\1xvTKqdLSn-vZSRQQCq2UYys6UZNMjPwG0SnEmPDa4L6HjeId1TH4RHO-Yvi8lWCDcmrp0bPCw=s800-c-k-c0x00ffffff-no-rj'
logoHighResUrl:
type: string
description: Url to Youtube account high res logo
format: URI
example: 'https:\\yt3.ggpht.com\1xvTKqdLSn-vZSRQQCq2UYys6UZNMjPwG0SnEmPDa4L6HjeId1TH4RHO-Yvi8lWCDcmrp0bPCw=s88-c-k-c0x00ffffff-no-rj'
title:
type: string
description: Youtube account title
example: Kim Kardashian
summary:
type: string
example: Exclusive videos from Kim Kardashian. Behind-the-scenes content beauty tutorials and more.
location:
type: string
nullable: true
example: ''
datePublished:
type: string
description: Unique youtube account id
format: date-time
example: '2015-06-26 22:46:50'
dateUpdated:
type: string
nullable: true
description: Unique youtube account id
format: date-time
example: '2015-06-26 22:46:50'
dateLastVideoUploaded:
type: string
nullable: true
description: Unique youtube account id
format: date-time
example: '2015-06-26 22:46:50'
uploadsPlaylistId:
type: string
description: Unique youtube account id
example: UUeNhHgTE36tTQkJsjPaPwnA
timeline:
type: object
properties:
type:
type: string
description: Type of Search
example: SocialPostsCollection
href:
type: string
description: CreatorIQ API URL to get creator's instagram stories
format: URI
example: 'https:\\apis.creatoriq.com\crm\v1\api\social\youtube\account\UCeNhHgTE36tTQkJsjPaPwnA\timeline'
verified:
type: string
nullable: true
example: ''
socialEngagement:
$ref: '#/components/schemas/SocialEngagement'
totalViews:
type: number
nullable: true
example: 89390026
totalLikes:
type: number
nullable: true
example: 89390026
totalDislikes:
type: number
nullable: true
example: 89390026
totalFavoritesAdded:
type: number
nullable: true
example: 89390026
totalComments:
type: number
nullable: true
example: 89390026
contentOwner:
type: string
nullable: true
example: ''
totalVideos:
type: number
nullable: true
example: 157
totalFavoritesRemoved:
type: number
nullable: true
example: 89390026
totalShares:
type: number
nullable: true
example: 89390026
totalSubscribers:
type: number
nullable: true
example: 1970000
estimatedMinutesWatched:
type: number
nullable: true
example: 89390026
averageViewDuration:
type: number
nullable: true
example: 89390026
averageMonthlyViews:
type: number
nullable: true
example: 993222.51111111
required:
- id
- url
SocialEngagement:
type: object
properties:
EngagementRate30Days:
type: string
nullable: true
example: ''
EngagementRate60Days:
type: string
nullable: true
example: ''
EngagementRate90Days:
type: number
nullable: true
example: 0.0061
EngagementRate20Posts:
type: number
nullable: true
example: 0.0202
EngagementRateLifetime:
type: number
nullable: true
example: 0.007
EngagementCalculated:
type: string
description: 'Timestamp of the most recent run of the engagement-metrics aggregation job for this account (calculates per-post and rolling-window engagement rates). Driven by its own background job on a different schedule from `LastUpdated` and `DateSocialStatsUpdated`, so the three timestamps can legitimately differ for the same account — some divergence between these timestamps is expected and does not indicate stale data.'
format: date-time
example: '2015-06-26 22:46:50'
PostsCount30Days:
type: number
nullable: true
example: 86705
PostsCount60Days:
type: number
nullable: true
example: 86705
PostsCount90Days:
type: number
nullable: true
example: 86705
PostsCountLifetime:
type: number
nullable: true
example: 86705
LastPostDate:
type: string
description: Unique youtube account id
format: date-time
example: '2015-06-26 22:46:50'
AVV30:
type: integer
nullable: true
example: 86705
AVV60:
type: integer
nullable: true
example: 86705
AVV90:
type: integer
nullable: true
example: 86705
ID:
type: number
example: 509137
AccountSource:
type: string
example: ''
Engagement30Days:
type: number
example: 86705
Engagement60Days:
type: number
example: 86705
Engagement90Days:
type: number
example: 86705
Engagement20Posts:
type: number
example: 86705
EngagementLifetime:
type: number
example: 86705
SharesPerPost30Days:
type: number
nullable: true
example: 86705
SharesPerPost60Days:
type: number
nullable: true
example: 86705
SharesPerPost90Days:
type: number
nullable: true
example: 86705
SharesPerPost20Posts:
type: number
nullable: true
example: 86705
SharesPerPostLifetime:
type: number
nullable: true
example: 86705
LikesPerPost30Days:
type: number
nullable: true
example: 86705
LikesPerPost60Days:
type: number
nullable: true
example: 86705
LikesPerPost90Days:
type: number
nullable: true
example: 86705
LikesPerPost20Posts:
type: number
nullable: true
example: 14233.65
LikesPerPostLifetime:
type: number
nullable: true
example: 3407.2684
CommentsPerPost30Days:
type: number
nullable: true
example: 86705
CommentsPerPost60Days:
type: number
nullable: true
example: 86705
CommentsPerPost90Days:
type: number
nullable: true
example: 527
CommentsPerPost20Posts:
type: number
nullable: true
example: 832.55
CommentsPerPostLifetime:
type: number
nullable: true
example: 90.8368
ViewsPerPost30Days:
type: number
nullable: true
example: 527
ViewsPerPost60Days:
type: number
nullable: true
example: 527
ViewsPerPost90Days:
type: number
nullable: true
example: 86705
ViewsPerPost20Posts:
type: number
nullable: true
example: 747087.15
ViewsPerPostLifetime:
type: number
nullable: true
example: 497148.1421
DisLikesPerPost30Days:
type: number
nullable: true
example: 547
DisLikesPerPost60Days:
type: number
nullable: true
example: 547
DisLikesPerPost90Days:
type: number
nullable: true
example: 547
DisLikesPerPost20Posts:
type: number
nullable: true
example: 547
DisLikesPerPostLifetime:
type: number
nullable: true
example: 547
CloseUpsPerPost30Days:
type: number
nullable: true
example: 547
CloseUpsPerPost60Days:
type: number
nullable: true
example: 547
CloseUpsPerPost90Days:
type: number
nullable: true
example: 547
CloseUpsPerPost20Posts:
type: number
nullable: true
example: 547
CloseUpsPerPostLifetime:
type: number
nullable: true
example: 547
ImpressionsPerPost30Days:
type: string
nullable: true
example: ''
ImpressionsPerPost60Days:
type: number
nullable: true
example: 547
ImpressionsPerPost90Days:
type: number
nullable: true
example: 547
# --- truncated at 32 KB (171 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/creatoriq/refs/heads/main/openapi/creatoriq-socials-openapi.yml