Archive Partners API

Archive API allows you to access enriched details about your community. The Archive Community is representative of the social profiles that are captured and tracked through an Archive Community CDP.

This detailed information ranges from profile information to post engagement metrics. This data has been used for enriching ambassador/loyalty programs, automating marketing flows, and performance measurement.

GraphQL

Archive API is built on GraphQL query language: graphql.org. If you already have an API token, you can try it with our API explorer.

API Endpoints
POST: https://app.archive.com/api/v1
Headers
# Get token from our team
Authorization: Bearer <YOUR_TOKEN_HERE>
# If you have multiple shops you need to pass Shop ID in header
SHOP-ID: 123
Contact

API Support

[email protected]

Authentication

All queries require a valid access token. In order to get your access token, contact api@archive.com. Include your token as an Authorization header on all queries.

Webhooks

You can receive webhooks for specific events. List of available events: WebhookSubscriptionsEventsEnum

To start receiving webhooks, you need to subscribe to an event with webhookSubscriptionCreate mutation. Once subscribed, Archive will send MediaItem object with attributes in underscore style to callback_url every time there is an event trigger.

Queries

creator

Description

Returns a Creator resource by ID.

Response

Returns a Creator!

Arguments
Name Description
id - Int
accountName - String
provider - ProvidersEnum

Example

Query
query creator(
  $id: Int,
  $accountName: String,
  $provider: ProvidersEnum
) {
  creator(
    id: $id,
    accountName: $accountName,
    provider: $provider
  ) {
    accountName
    avatarUrl
    biography
    followersCount
    followingCount
    id
    provider
    verified
  }
}
Variables
{
  "id": 987,
  "accountName": "xyz789",
  "provider": "INSTAGRAM"
}
Response
{
  "data": {
    "creator": {
      "accountName": "xyz789",
      "avatarUrl": "abc123",
      "biography": "xyz789",
      "followersCount": 987,
      "followingCount": 123,
      "id": 987,
      "provider": "INSTAGRAM",
      "verified": true
    }
  }
}

creatorAudienceReport

Description

Returns a Creator audience report.

Response

Returns an AudienceReportResponse!

Arguments
Name Description
id - Int
accountName - String

Example

Query
query creatorAudienceReport(
  $id: Int,
  $accountName: String
) {
  creatorAudienceReport(
    id: $id,
    accountName: $accountName
  ) {
    accountName
    audienceReport
    id
    provider
  }
}
Variables
{"id": 123, "accountName": "xyz789"}
Response
{
  "data": {
    "creatorAudienceReport": {
      "accountName": "xyz789",
      "audienceReport": {},
      "id": 123,
      "provider": "INSTAGRAM"
    }
  }
}

creatorPosts

Description

Returns a Creator posts.

Response

Returns a MediaItemConnection!

Arguments
Name Description
id - Int
accountName - String
provider - ProvidersEnum
after - String Returns the elements in the list that come after the specified cursor.
before - String Returns the elements in the list that come before the specified cursor.
first - Int Returns the first n elements from the list.
last - Int Returns the last n elements from the list.

Example

Query
query creatorPosts(
  $id: Int,
  $accountName: String,
  $provider: ProvidersEnum,
  $after: String,
  $before: String,
  $first: Int,
  $last: Int
) {
  creatorPosts(
    id: $id,
    accountName: $accountName,
    provider: $provider,
    after: $after,
    before: $before,
    first: $first,
    last: $last
  ) {
    edges {
      cursor
      node {
        caption
        contents {
          contentUrl
          displayUrl
          height
          id
          type
          width
        }
        creator {
          accountName
          avatarUrl
          biography
          followersCount
          followingCount
          id
          provider
          verified
        }
        engagement {
          at
          commentCount
          likeCount
          playCount
          viewCount
        }
        engagementHistory {
          at
          commentCount
          likeCount
          playCount
          viewCount
        }
        externalId
        hashtags
        id
        location {
          address
          city
          lat
          lng
          name
        }
        mentions
        provider
        takenAt
        type
        usageRightsStatus
      }
    }
    nodes {
      caption
      contents {
        contentUrl
        displayUrl
        height
        id
        type
        width
      }
      creator {
        accountName
        avatarUrl
        biography
        followersCount
        followingCount
        id
        provider
        verified
      }
      engagement {
        at
        commentCount
        likeCount
        playCount
        viewCount
      }
      engagementHistory {
        at
        commentCount
        likeCount
        playCount
        viewCount
      }
      externalId
      hashtags
      id
      location {
        address
        city
        lat
        lng
        name
      }
      mentions
      provider
      takenAt
      type
      usageRightsStatus
    }
    pageInfo {
      endCursor
      hasNextPage
      hasPreviousPage
      startCursor
    }
    totalCount
  }
}
Variables
{
  "id": 123,
  "accountName": "abc123",
  "provider": "INSTAGRAM",
  "after": "abc123",
  "before": "abc123",
  "first": 987,
  "last": 987
}
Response
{
  "data": {
    "creatorPosts": {
      "edges": [MediaItemEdge],
      "nodes": [MediaItem],
      "pageInfo": PageInfo,
      "totalCount": 123
    }
  }
}

mediaItem

Description

Returns a MediaItem resource by ID or externalID.

Response

Returns a MediaItem

Arguments
Name Description
id - String
externalId - String

Example

Query
query mediaItem(
  $id: String,
  $externalId: String
) {
  mediaItem(
    id: $id,
    externalId: $externalId
  ) {
    caption
    contents {
      contentUrl
      displayUrl
      height
      id
      type
      width
    }
    creator {
      accountName
      avatarUrl
      biography
      followersCount
      followingCount
      id
      provider
      verified
    }
    engagement {
      at
      commentCount
      likeCount
      playCount
      viewCount
    }
    engagementHistory {
      at
      commentCount
      likeCount
      playCount
      viewCount
    }
    externalId
    hashtags
    id
    location {
      address
      city
      lat
      lng
      name
    }
    mentions
    provider
    takenAt
    type
    usageRightsStatus
  }
}
Variables
{
  "id": "abc123",
  "externalId": "xyz789"
}
Response
{
  "data": {
    "mediaItem": {
      "caption": "xyz789",
      "contents": [MediaContent],
      "creator": Creator,
      "engagement": [MediaItemsEngagement],
      "engagementHistory": [MediaItemsEngagement],
      "externalId": "abc123",
      "hashtags": ["abc123"],
      "id": 4,
      "location": MediaItemLocation,
      "mentions": ["xyz789"],
      "provider": "INSTAGRAM",
      "takenAt": ISO8601DateTime,
      "type": "POST",
      "usageRightsStatus": "REQUESTED"
    }
  }
}

mediaItems

Description

Gets portion of media items.

Response

Returns a MediaItemConnection!

Arguments
Name Description
filter - Filter
after - String Returns the elements in the list that come after the specified cursor.
before - String Returns the elements in the list that come before the specified cursor.
first - Int Returns the first n elements from the list.
last - Int Returns the last n elements from the list.

Example

Query
query mediaItems(
  $filter: Filter,
  $after: String,
  $before: String,
  $first: Int,
  $last: Int
) {
  mediaItems(
    filter: $filter,
    after: $after,
    before: $before,
    first: $first,
    last: $last
  ) {
    edges {
      cursor
      node {
        caption
        contents {
          contentUrl
          displayUrl
          height
          id
          type
          width
        }
        creator {
          accountName
          avatarUrl
          biography
          followersCount
          followingCount
          id
          provider
          verified
        }
        engagement {
          at
          commentCount
          likeCount
          playCount
          viewCount
        }
        engagementHistory {
          at
          commentCount
          likeCount
          playCount
          viewCount
        }
        externalId
        hashtags
        id
        location {
          address
          city
          lat
          lng
          name
        }
        mentions
        provider
        takenAt
        type
        usageRightsStatus
      }
    }
    nodes {
      caption
      contents {
        contentUrl
        displayUrl
        height
        id
        type
        width
      }
      creator {
        accountName
        avatarUrl
        biography
        followersCount
        followingCount
        id
        provider
        verified
      }
      engagement {
        at
        commentCount
        likeCount
        playCount
        viewCount
      }
      engagementHistory {
        at
        commentCount
        likeCount
        playCount
        viewCount
      }
      externalId
      hashtags
      id
      location {
        address
        city
        lat
        lng
        name
      }
      mentions
      provider
      takenAt
      type
      usageRightsStatus
    }
    pageInfo {
      endCursor
      hasNextPage
      hasPreviousPage
      startCursor
    }
    totalCount
  }
}
Variables
{
  "filter": Filter,
  "after": "abc123",
  "before": "abc123",
  "first": 123,
  "last": 123
}
Response
{
  "data": {
    "mediaItems": {
      "edges": [MediaItemEdge],
      "nodes": [MediaItem],
      "pageInfo": PageInfo,
      "totalCount": 123
    }
  }
}

webhookSubscriptions

Description

Gets list of webhook subscriptions by event.

Response

Returns [WebhookSubscription!]

Arguments
Name Description
event - WebhookSubscriptionsEventsEnum

Example

Query
query webhookSubscriptions($event: WebhookSubscriptionsEventsEnum) {
  webhookSubscriptions(event: $event) {
    callbackUrl
    event
    id
    version
  }
}
Variables
{"event": "MEDIA_ITEM_CREATED"}
Response
{
  "data": {
    "webhookSubscriptions": [
      {
        "callbackUrl": "abc123",
        "event": "MEDIA_ITEM_CREATED",
        "id": "4",
        "version": "v0"
      }
    ]
  }
}

Mutations

creatorTrackingStart

Description

Start track media items from Creator.

Response

Returns a Creator

Arguments
Name Description
id - Int!

Example

Query
mutation creatorTrackingStart($id: Int!) {
  creatorTrackingStart(id: $id) {
    accountName
    avatarUrl
    biography
    followersCount
    followingCount
    id
    provider
    verified
  }
}
Variables
{"id": 987}
Response
{
  "data": {
    "creatorTrackingStart": {
      "accountName": "xyz789",
      "avatarUrl": "xyz789",
      "biography": "abc123",
      "followersCount": 987,
      "followingCount": 987,
      "id": 123,
      "provider": "INSTAGRAM",
      "verified": false
    }
  }
}

creatorTrackingStop

Description

Stop track media items from Creator.

Response

Returns a Creator

Arguments
Name Description
id - Int!

Example

Query
mutation creatorTrackingStop($id: Int!) {
  creatorTrackingStop(id: $id) {
    accountName
    avatarUrl
    biography
    followersCount
    followingCount
    id
    provider
    verified
  }
}
Variables
{"id": 987}
Response
{
  "data": {
    "creatorTrackingStop": {
      "accountName": "xyz789",
      "avatarUrl": "abc123",
      "biography": "xyz789",
      "followersCount": 123,
      "followingCount": 123,
      "id": 123,
      "provider": "INSTAGRAM",
      "verified": true
    }
  }
}

webhookSubscriptionCreate

Description

Creates a new webhook subscription.

Response

Returns a WebhookSubscription

Arguments
Name Description
version - WebhookSubscriptionsVersionsEnum!
event - WebhookSubscriptionsEventsEnum!
callbackUrl - String!

Example

Query
mutation webhookSubscriptionCreate(
  $version: WebhookSubscriptionsVersionsEnum!,
  $event: WebhookSubscriptionsEventsEnum!,
  $callbackUrl: String!
) {
  webhookSubscriptionCreate(
    version: $version,
    event: $event,
    callbackUrl: $callbackUrl
  ) {
    callbackUrl
    event
    id
    version
  }
}
Variables
{
  "version": "v0",
  "event": "MEDIA_ITEM_CREATED",
  "callbackUrl": "xyz789"
}
Response
{
  "data": {
    "webhookSubscriptionCreate": {
      "callbackUrl": "abc123",
      "event": "MEDIA_ITEM_CREATED",
      "id": "4",
      "version": "v0"
    }
  }
}

webhookSubscriptionDelete

Description

Deletes a webhook subscription.

Response

Returns a Boolean

Arguments
Name Description
event - WebhookSubscriptionsEventsEnum!

Example

Query
mutation webhookSubscriptionDelete($event: WebhookSubscriptionsEventsEnum!) {
  webhookSubscriptionDelete(event: $event)
}
Variables
{"event": "MEDIA_ITEM_CREATED"}
Response
{"data": {"webhookSubscriptionDelete": true}}

Types

AudienceReportResponse

Fields
Field Name Description
accountName - String! Name of creator account on Instagram or TikTok.
audienceReport - JSON! Audience report.
id - Int! Creator's unique identifier in Archive's system.
provider - ProvidersEnum! Platform where creator exists. INSTAGRAM or TIKTOK.
Example
{
  "accountName": "abc123",
  "audienceReport": {},
  "id": 123,
  "provider": "INSTAGRAM"
}

Boolean

Description

Represents true or false values.

Creator

Fields
Field Name Description
accountName - String! Name of creator account on Instagram or TikTok.
avatarUrl - String URL of the creator's profile picture.
biography - String Creator's bio (if available).
followersCount - Int Number of creator's followers.
followingCount - Int Number of accounts creator is following.
id - Int! Unique identifier in Archive's system.
provider - ProvidersEnum! Platform where creator exists. INSTAGRAM or TIKTOK.
verified - Boolean Whether the creator is verified by the platform.
Example
{
  "accountName": "xyz789",
  "avatarUrl": "xyz789",
  "biography": "xyz789",
  "followersCount": 987,
  "followingCount": 987,
  "id": 987,
  "provider": "INSTAGRAM",
  "verified": true
}

Filter

Fields
Input Field Description
itemTypes - [TypesEnum!] Types of the items
creatorAccountName - [String!] Creator Account Names. Default = []
creatorVerified - [Boolean!] Only verified influencers
usageRightsStatus - [StatusesEnum!] Usage Rights request status
Example
{
  "itemTypes": ["POST"],
  "creatorAccountName": ["xyz789"],
  "creatorVerified": [false],
  "usageRightsStatus": ["REQUESTED"]
}

ID

Description

Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as "VXNlci0xMA==") or integer (such as 4) input value will be accepted as an ID.

Example
4

ISO8601DateTime

Description

An ISO 8601-encoded datetime

Example
ISO8601DateTime

Int

Description

Represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.

Example
123

JSON

Description

Represents untyped JSON

Example
{}

MediaContent

Fields
Field Name Description
contentUrl - String URL of image or video file.
displayUrl - String URL of video thumbnail. Will be the same as content_url for images.
height - Int Height of media file in px.
id - Int! Unique identifier in Archive's system.
type - String! Type of media file. IMAGE or VIDEO.
width - Int Width of media file in px.
Example
{
  "contentUrl": "xyz789",
  "displayUrl": "xyz789",
  "height": 123,
  "id": 123,
  "type": "xyz789",
  "width": 987
}

MediaItem

Fields
Field Name Description
caption - String Content caption.
contents - [MediaContent!]! Files which represent the content of an item. For carousels, there will be multiple.
creator - Creator! Information about the content creator.
engagement - [MediaItemsEngagement!] We can track posts for X days and gather post engagement dynamics.
engagementHistory - [MediaItemsEngagement!] We can track posts for X days and gather post engagement dynamics.
externalId - String! The ID of an item on Instagram or TikTok.
hashtags - [String!] Hashtags that are used in the content.
id - ID! Unique identifier in Archive's system.
location - MediaItemLocation Content location description.
mentions - [String!] Mentions that are used in the content.
provider - ProvidersEnum! Platform where content exists. INSTAGRAM or TIKTOK.
takenAt - ISO8601DateTime! Timestamp of when content was uploaded to social media (UTC).
type - TypesEnum! Type of archived content. POST, REEL, STORY or TIKTOK.
usageRightsStatus - StatusesEnum Status of usage rights request for content. REQUESTED, APPROVED or REJECTED.
Example
{
  "caption": "xyz789",
  "contents": [MediaContent],
  "creator": Creator,
  "engagement": [MediaItemsEngagement],
  "engagementHistory": [MediaItemsEngagement],
  "externalId": "xyz789",
  "hashtags": ["abc123"],
  "id": "4",
  "location": MediaItemLocation,
  "mentions": ["xyz789"],
  "provider": "INSTAGRAM",
  "takenAt": ISO8601DateTime,
  "type": "POST",
  "usageRightsStatus": "REQUESTED"
}

MediaItemConnection

Description

The connection type for MediaItem.

Fields
Field Name Description
edges - [MediaItemEdge] A list of edges.
nodes - [MediaItem] A list of nodes.
pageInfo - PageInfo! Information to aid in pagination.
totalCount - Int!
Example
{
  "edges": [MediaItemEdge],
  "nodes": [MediaItem],
  "pageInfo": PageInfo,
  "totalCount": 123
}

MediaItemEdge

Description

An edge in a connection.

Fields
Field Name Description
cursor - String! A cursor for use in pagination.
node - MediaItem The item at the end of the edge.
Example
{
  "cursor": "xyz789",
  "node": MediaItem
}

MediaItemLocation

Fields
Field Name Description
address - String
city - String
lat - String
lng - String
name - String
Example
{
  "address": "abc123",
  "city": "xyz789",
  "lat": "xyz789",
  "lng": "xyz789",
  "name": "abc123"
}

MediaItemsEngagement

Fields
Field Name Description
at - ISO8601DateTime! Timestamp of when engagement metrics were captured.
commentCount - Int Number of comments.
likeCount - Int Number of likes.
playCount - Int Number of plays (if available).
viewCount - Int Number of views (if available).
Example
{
  "at": ISO8601DateTime,
  "commentCount": 987,
  "likeCount": 987,
  "playCount": 123,
  "viewCount": 987
}

PageInfo

Description

Information about pagination in a connection.

Fields
Field Name Description
endCursor - String When paginating forwards, the cursor to continue.
hasNextPage - Boolean! When paginating forwards, are there more items?
hasPreviousPage - Boolean! When paginating backwards, are there more items?
startCursor - String When paginating backwards, the cursor to continue.
Example
{
  "endCursor": "abc123",
  "hasNextPage": false,
  "hasPreviousPage": true,
  "startCursor": "abc123"
}

ProvidersEnum

Values
Enum Value Description

INSTAGRAM

TIKTOK

Example
"INSTAGRAM"

StatusesEnum

Values
Enum Value Description

REQUESTED

APPROVED

REJECTED

Example
"REQUESTED"

String

Description

Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.

Example
"xyz789"

TypesEnum

Values
Enum Value Description

POST

STORY

REEL

Example
"POST"

WebhookSubscription

Fields
Field Name Description
callbackUrl - String! URL of where we will send webhook payload.
event - WebhookSubscriptionsEventsEnum! Event which triggers webhook.
id - ID! Unique identifier in Archive's system.
version - WebhookSubscriptionsVersionsEnum! Which version of payloads are used.
Example
{
  "callbackUrl": "xyz789",
  "event": "MEDIA_ITEM_CREATED",
  "id": "4",
  "version": "v0"
}

WebhookSubscriptionsEventsEnum

Values
Enum Value Description

MEDIA_ITEM_CREATED

Triggers when media item comes to Archive.

MEDIA_ITEM_ENGAGEMENT_UPDATED

Triggers when we add a record into media item engagement history.
Example
"MEDIA_ITEM_CREATED"

WebhookSubscriptionsVersionsEnum

Values
Enum Value Description

v0

v1

Example
"v0"