Instagram Data Model

Instagram is a social media platform where users share photos and videos, connect with others, and discover new content.

Instagram Tables #

The Instagram connector models the data in Instagram as a list of tables in a relational database that can be queried using standard SQL statements.

Comments #

Create, delete, and query Comments on a media object. Requires the instagram_basic and instagram_manage_comments scopes.

Only the select, delete, and insert operations are supported.

Select

The connector will use the Instagram APIs to filter results by MediaId and will execute other filters client-side within itself.

• The following query returns all comments on all media in your account. UserId will be null if the comment is from an account that is not a business account.

  SELECT * FROM Comments

• To query comments for a specific media object, MediaId is required. The MediaId column supports the = operator. For example:

  SELECT * FROM Comments WHERE MediaId = '1501471279105199430_5380790872'

Insert

Create a comment on a media object with the following rules:

• MediaId and Text are the only available and required fields.

• The total length of the comment cannot exceed 300 characters.

• The comment cannot contain more than 4 hashtags.

• The comment cannot contain more than 1 URL.

• The comment cannot consist of all capital letters.

Example:

INSERT INTO Comments (MediaId, Text) VALUES ('1501471279105199430_5380790872', 'My comment text #instadevelopers')

Columns

Replies #

Query and insert replies on a media object. Requires the instagram_basic and instagram_manage_comments scopes.

Only the select and insert operations are supported.

Select

The connector will process a filter on CommentId server side and will execute other filters client-side within itself.

• The following query returns replies from all comments in your account. UserId will be null if the reply is from an account that is not a business account.

  SELECT * FROM Replies

• To query replies for a specific comment, CommentId is required. The supported operator for the CommentId column is =.

Example:

SELECT * FROM Replies WHERE CommentId = '1501471279105199430_5380790872'

Insert

Create a reply on a comment object with the following rules:

• CommentId and Text are the only available and required fields.

• The total length of the comment cannot exceed 300 characters.

• The reply cannot contain more than 4 hashtags.

• The reply cannot contain more than 1 URL.

• The reply cannot consist of all capital letters.

Example:

INSERT INTO Replies (CommentId, Text) VALUES ('1501471279105199430_5380790872', 'My reply #instadevelopers')

Columns

Instagram Views #

Views are similar to tables in the way that data is represented; however, views are read-only.

Queries can be executed against a view as if it were a normal table.

AccountContactButtonType #

It returns the number of taps on the DIRECTION, CALLs and EMAILs button during the selected time period.

For this view, the Metric Type is total_value and Breakdown(dimension) is contact_button_type. Requires the instagram_basic and instagram_manage_insights scopes.

Select

The connector will use the Instagram APIs to process filters that refer to a date range or InstagramBusinessAccountId and will process other filters client-side within itself.

• Metric supports the ‘=’ operator.

  The default query returns results for the ‘profile_links_taps’ metric.

  SELECT * FROM AccountContactButtonType

  SELECT * FROM AccountContactButtonType WHERE FromDateTime='2023-07-02T00:00:00Z' AND ToDateTime='2023-07-24T00:00:00Z'

Columns

Pseudo-Columns

Pseudo column fields are used in the WHERE clause of SELECT statements and offer a more granular control over the tuples that are returned from the data source.

AccountFollowersNonfollowers #

The number of accounts that followed and the number of accounts that unfollowed or stopped using Instagram during the selected time period.

For this view, the Metric Type is total_value and Breakdown(dimension) is follow_type. Requires the instagram_basic and instagram_manage_insights scopes.

Select

The connector will use the Instagram APIs to process filters that refer to a date range or InstagramBusinessAccountId and will process other filters client-side within itself.

• Metric supports the ‘=,IN’ operator.

  The default query returns results for the ‘follows_and_unfollows’ metric.

  SELECT * FROM AccountFollowersNonfollowers

  SELECT * FROM AccountFollowersNonfollowers WHERE FromDateTime='2023-06-20T00:00:00Z' AND ToDateTime='2023-07-12T00:00:00Z'

  To retrieve the result for other metrics, then explicitly specify the Metric in where clause. For example:

  SELECT * FROM AccountFollowersNonfollowers WHERE Metric = 'reach'

  SELECT * FROM AccountFollowersNonfollowers WHERE Metric IN ('follows\_and\_unfollows', 'reach')

Columns

Pseudo-Columns

Pseudo column fields are used in the WHERE clause of SELECT statements and offer a more granular control over the tuples that are returned from the data source.

AccountInsights #

Allows you to get insights for an Instagram business account. Requires the instagram_basic and instagram_manage_insights scopes.

Select

You can query the following metrics given a date range. The default date range is the last 7 days.

• Impressions (accepts time periods of day, week, and days_28)

• Reach (accepts time periods of day, week, and days_28)

• FollowerCount (only accepts the day period)

• EmailContacts (only accepts the day period)

• PhoneCallClicks (only accepts the day period)

• TextMessageClicks (only accepts the day period)

• GetDirectionsClicks (only accepts the day period)

• WebsiteClicks (only accepts the day period)

• ProfileViews (only accepts the day period)

Specify a date range with the FromDateTime and ToDateTime columns. Specify the intervals of the date range by setting the Period column in the WHERE clause.

Note that you cannot use a period on a metric that does not support it.

For example, you cannot use Impressions AND FollowerCount with period days_28 because FollowerCount only supports the day period.

The connector will use the Instagram APIs to process filters that refer to a date range or Id.

The following examples show how to retrieve metrics over a given date range:

• The default query returns results for the following metrics during the last seven days: Impressions, Reach, FollowerCount, EmailContacts, PhoneCallClicks, TextMessageClicks, GetDirectionsClicks, WebsiteClicks, and ProfileViews.

  SELECT * FROM AccountInsights

• Filter on FromDateTime and ToDateTime to explicitly specify a different date range. The max date range cannot be more than 30 days (2592000 s).

  SELECT * FROM AccountInsights WHERE FromDateTime = '2018/01/01' AND ToDateTime = '2018/01/30' AND period = 'day'

• Return results over a period of 7 days.

  SELECT * FROM AccountInsights WHERE FromDateTime = '2018/01/01' AND period = 'day'

• Return results from 2018/01/01 to 2018/01/08.

  SELECT * FROM AccountInsights WHERE ToDateTime = '2018/01/08' AND period = 'day'

• Return a custom projection on account insights for the date range from 2018/01/01 to 2018/01/08.

  SELECT Impressions, FollowerCount, EmailContacts FROM AccountInsights WHERE FromDateTime = '2018/01/01' AND ToDateTime = '2018/01/30' AND period = 'day'

Columns

Pseudo-Columns

Pseudo column fields are used in the WHERE clause of SELECT statements and offer a more granular control over the tuples that are returned from the data source.

AccountMediaProductType #

It returns the number of POSTs and IGTVs during the selected time period.

For this view, the Metric Type is total_value and Breakdown(dimension) is media_product_type. Requires the instagram_basic and instagram_manage_insights scopes.

Select

The connector will use the Instagram APIs to process filters that refer to a date range or InstagramBusinessAccountId and will process other filters client-side within itself.

• Metric supports the ‘=,IN’ operator.

  The default query returns results for the ‘reach’ metric.

  SELECT * FROM AccountMediaProductType

  SELECT * FROM AccountMediaProductType WHERE FromDateTime='2023-06-20T00:00:00Z' AND ToDateTime='2023-07-12T00:00:00Z'

To retrieve the result for other available metric, then explicitly specify the Metric in where clause.

Example:

SELECT * FROM AccountMediaProductType WHERE Metric = 'total_interactions'

SELECT * FROM AccountMediaProductType WHERE Metric = 'likes'

SELECT * FROM AccountMediaProductType WHERE Metric = 'comments'

SELECT * FROM AccountMediaProductType WHERE Metric = 'saves'

SELECT * FROM AccountMediaProductType WHERE Metric = 'shares'

SELECT * FROM AccountMediaProductType WHERE Metric IN ('total_interactions', 'likes', 'comments', 'saves', 'shares')

Columns

Pseudo-Columns

Pseudo column fields are used in the WHERE clause of SELECT statements and offer a more granular control over the tuples that are returned from the data source.

AccountTimeSeriesFollowType #

It returns the metric endtime and the value. For this view, the Metric type is time_series and breakdown is follow_type. Requires the instagram_basic and instagram_manage_insights scopes.

Select

The connector will use the Instagram APIs to process filters that refer to a date range or InstagramBusinessAccountId and will process other filters client-side within itself.

• Metric supports the ‘=’ operator.

  The default query returns results for the ‘reach’ metric.

  SELECT * FROM AccountTimeSeriesFollowType

  SELECT * FROM AccountTimeSeriesFollowType WHERE FromDateTime='2023-06-20T00:00:00Z' AND ToDateTime='2023-07-12T00:00:00Z'

Columns

Pseudo-Columns

Pseudo column fields are used in the WHERE clause of SELECT statements and offer a more granular control over the tuples that are returned from the data source.

AccountTimeSeriesMediaProductType #

It returns the metric endtime and the value. For this view, the Metric type is time_series and breakdown is media_product_type. Requires the instagram_basic and instagram_manage_insights scopes.

Select

The connector will use the Instagram APIs to process filters that refer to a date range or InstagramBusinessAccountId and will process other filters client-side within itself.

• Metric supports the ‘=’ operator.

  The default query returns results for the ‘reach’ metric.

  SELECT * FROM AccountTimeSeriesMediaProductType

  SELECT * FROM AccountTimeSeriesMediaProductType WHERE FromDateTime='2023-06-20T00:00:00Z' AND ToDateTime='2023-07-12T00:00:00Z'

Columns

Pseudo-Columns

Pseudo column fields are used in the WHERE clause of SELECT statements and offer a more granular control over the tuples that are returned from the data source.

AccountTimeSeriesWithoutBreakdown #

It returns the metric endtime and the value. For this view, the Metric type is time_series. Requires the instagram_basic and instagram_manage_insights scopes.

Select

The connector will use the Instagram APIs to process filters that refer to a date range or InstagramBusinessAccountId and will process other filters client-side within itself.

• Metric supports the ‘=’ operator.

  The default query returns results for the ‘impressions’ metric.

  SELECT * FROM AccountTimeSeriesWithoutBreakdown

  SELECT * FROM AccountTimeSeriesWithoutBreakdown WHERE FromDateTime='2023-06-20T00:00:00Z' AND ToDateTime='2023-07-12T00:00:00Z'

Columns

Pseudo-Columns

Pseudo column fields are used in the WHERE clause of SELECT statements and offer a more granular control over the tuples that are returned from the data source.

AccountWithoutBreakdown #

It returns the total values of the metric type in Instagram. For example, if the metric type is impressions, it will return the number of times your posts, stories, reels, videos and live videos were on screen, including in ads.

For this view, the Metric Type is total_value. Requires the instagram_basic and instagram_manage_insights scopes.

Select

The connector will use the Instagram APIs to process filters that refer to a date range or InstagramBusinessAccountId and will process other filters client-side within itself.

• Metric supports the ‘=,IN’ operator.

  The default query returns results for the ‘impressions’ metric.

  SELECT * FROM AccountWithoutBreakdown

  SELECT * FROM AccountWithoutBreakdown WHERE FromDateTime='2023-06-20T00:00:00Z' AND ToDateTime='2023-07-12T00:00:00Z'

To retrieve the result for other available metric, then explicitly specify the Metric in where clause.

Example:

SELECT * FROM AccountWithoutBreakdown WHERE Metric = 'accounts_engaged'

SELECT * FROM AccountWithoutBreakdown WHERE Metric = 'replies'

SELECT * FROM AccountWithoutBreakdown WHERE Metric = 'website_clicks'

SELECT * FROM AccountWithoutBreakdown WHERE Metric = 'profile_views'

SELECT * FROM AccountWithoutBreakdown WHERE Metric IN ('accounts\_engaged', 'replies', 'website\_clicks', 'profile_views')

Columns

Pseudo-Columns

Pseudo column fields are used in the WHERE clause of SELECT statements and offer a more granular control over the tuples that are returned from the data source.

AudienceInsights #

Retrieve follower insights for an Instagram business account.

Select

By default this table returns the following:

• The countries of this profile’s followers.

To return any of the below demographic information about your followers:

• The gender and age distribution of this profile’s followers.

• The locales of this profile’s followers, by country code.

• The cities of this profile’s followers.

you will need to filter on the AudienceType column:

SELECT * FROM AudienceInsights WHERE AudienceType='country'

SELECT * FROM AudienceInsights WHERE AudienceType IN ('city','country','genderandage')

The above query will return follower counts broken down by city, follower counts broken down by country, and follower counts broken down by gender and age.

Valid values for the AudienceType column are:

• city

• country

• gender

• age

• genderandage

Columns

IGMedia #

This View Represents an Instagram Photo, Video, Story, Album, or IGTV media.

Select

The connector will use the Instagram API to process WHERE clause conditions built with the following columns and operators. The rest of the filter is executed client side within the connector.

• Id supports the ‘=’ operator.

For example, the following query is processed server side:

SELECT * FROM IGMedia WHERE Id = '1234'

Columns

InstagramBusinessProfile #

Get information about the Instagram Business account. Requires the instagram_basic scope, business_management, manage_pages .

Select

The connector will process all filters on this table client-side within itself.

Columns

InstagramPages #

Query information about pages connected to the Facebook account. Requires the instagram_basic scope.

Select

The connector will process all filters client-side within itself. You can use this table to obtain the value of the BusinessAccountId connection property:

SELECT Name, InstagramBusinessAccountId FROM Pages

Columns

Media #

Query media objects. Requires the instagram_basic and instagram_content_publish scopes.

Select

The connector will use the Instagram APIs to process filters by Id and will process other filters client-side within itself.

The following query gets all media published by the authenticated user:

SELECT * FROM Media

To retrieve a single media object, the Id is required. The Id column supports the = operator. For example:

SELECT * FROM Media WHERE Id = '1501471279105199430_5380790872'

Columns

MediaInsightReels #

Allows you to get insights for reel media object. Requires the instagram_basic and instagram_manage_insights scopes.

Select

You can query the following metrics using server-side processing:

• Reach

• Comments

• Likes

• Saved

• Plays

• Shares

• TotalInteractions

The connector will use the Instagram APIs to process filters by a MediaId and will process filters on other columns client-side within itself.

• MediaInsightReels will only return the result of reels object.

• Return results for the following metrics, saved for all the reels objects: Reach, Saved, Comments, Likes, Plays, Shares and TotalInteractions.

  SELECT * FROM MediaInsightReels WHERE MediaId = 17905513811523370"

  SELECT Reach, Saved, Comments, Likes, Plays, Shares, TotalInteractions FROM MediaInsightReels WHERE MediaId = 17905513811523370

Columns

MediaInsights #

Allows you to get insights for an individual media object. Requires the instagram_basic and instagram_manage_insights scopes.

Select

You can query the following metrics using server-side processing:

• Impressions

• Engagement (likes, comments, and saves)

• Reach

• Saved

• Videoviews (only on a video object)

• TapsForward (only on a story object)

• TapsBack (only on a story object)

• Exits (only on a story object)

• Replies (only on a story object)

The connector will use the Instagram APIs to process filters by a MediaId and will process filters on other columns client-side within itself.

• MediaInsights will return result of all media objects except reels object.

• Return results for the following metrics, saved for all the image and carousel objects: impressions, engagement, and reach.

  SELECT * FROM MediaInsights

• Query the MediaInsights view using a different object, for example, stories.

  SELECT TapsForward, TapsBack FROM MediaInsights WHERE MediaId = "132155564886465"

• Query the MediaInsights view using a different object, for example, videos.

  SELECT Impressions, Engagement, Reach, Saved, VideoViews FROM MediaInsights WHERE MediaId = "1321555648546465"

Columns

MediaInsightsPost #

Allows you to get insights for an individual media object for POSTs. Requires the instagram_basic and instagram_manage_insights scopes.

Select

You can query the following metrics using server-side processing:

• Comments

• Follows

• Likes

• ProfileActivity

• ProfileVisits

• Shares

• TotalInteractions

The connector will use the Instagram APIs to process filters by a MediaId and will process filters on other columns client-side within itself.

• Return results for the following metrics, saved for all the POSTs objects: Comments, Follows, Likes, ProfileActivity, ProfileVisits, Shares and TotalInteractions.

  SELECT * FROM MediaInsightsPost WHERE MediaId = 17945732813652602"

  SELECT Comments, Follows, Likes, ProfileActivity, ProfileVisits, Shares, TotalInteractions FROM MediaInsightsPost WHERE MediaId = 17945732813652602

Columns

MediaInsightsStory #

Allows you to get insights for an individual media object for Story. Requires the instagram_basic and instagram_manage_insights scopes.

Select

You can query the following metrics using server-side processing:

• Follows

• ProfileActivity

• ProfileVisits

• Shares

• TotalInteractions

The connector will use the Instagram APIs to process filters by a MediaId and will process filters on other columns client-side within itself.

• Return results for the following metrics, saved for all the Story objects: Follows, ProfileActivity, ProfileVisits, Shares and TotalInteractions.

  SELECT * FROM MediaInsightsStory WHERE MediaId = 17945732813652602"

  SELECT Comments, Follows, Likes, ProfileActivity, ProfileVisits, Shares, TotalInteractions FROM MediaInsightsStory WHERE MediaId = 17945732813652602

Columns

OnlineFollowers #

Query Online Followers insights as hourly totals. Requires the instagram_basic and instagram_manage_insights scopes.

Select

You can use the FromDateTime and ToDateTime columns to filter the results by a timeframe. The connector uses the Instagram API to process filters that refer to a timeframe or Id and will process other filters client-side within itself.

• The default query returns results as hourly totals during the last 7 days.

  SELECT * FROM OnlineFollowers

• The maximum timeframe you can specify with the FromDateTime and ToDateTime columns is 30 days (2592000 s).

  SELECT * FROM OnlineFollowers WHERE FromDateTime = '2018/01/01' AND ToDateTime = '2018/01/30'

Columns

Pseudo-Columns

Pseudo column fields are used in the WHERE clause of SELECT statements and offer a more granular control over the tuples that are returned from the data source.

Pages #

Get details of Pages. Requires ‘pages_read_engagement’ permission or the ‘Page Public Content Access’ feature or the ‘Page Public Metadata Access’ feature.

Select

The connector will use the Instagram API to process WHERE clause conditions built with the following column and operator. The SearchTerms is required to make a request and the rest of the filter is executed client side within the connector.

• SearchTerms supports the ‘=’ comparison.

  Example:

  SELECT * FROM Pages WHERE SearchTerms = 'facebook'

Columns

Pseudo-Columns

Pseudo column fields are used in the WHERE clause of SELECT statements and offer a more granular control over the tuples that are returned from the data source.

Permissions #

Query the Permissions the User has granted the current application.

Select

To query the Permissions view.

SELECT * FROM Permissions

Columns

Stories #

Query Stories. Requires the instagram_basic and instagram_manage_insights scopes.

Select

The connector process all filters on this table client-side within itself.

Columns

Tags #

Query tags. Requires the instagram_basic and instagram_manage_comments scopes.

Select

The connector processes all filters on this table client-side within itself.

Columns