Twitter API Reference

The public API procedures may call the internal procedures which should not be used directly as they can be changed without any explicit notification in the newer versions of the connector. Internal procedures can be recognized by the internal_ prefix in their names. Public API procedures do not have such prefixes in their names.

Analytics

Twitter Ad metrics
Parameter
<accountId> (required): Twitter Account ID
<periodDuration> (required): Duration of a single batch: max 45 for HOUR/async, 7 for HOUR/sync, and 90 for DAY/TOTAL
<twitterEntityType> (required): Entity type: ACCOUNT, CAMPAIGN, LINE_ITEM, or PROMOTED_TWEET
<granularity> (required): Metrics granularity: HOUR, DAY, or TOTAL
<withDeleted> (optional): Include deleted items (only applicable when entityIds is null, otherwise ignored)
<twitterSegmentationType> (optional): Segmentation type
<idPortion> (optional): How many IDs to query at the same time, default 20
<entityIds> (optional): Request data for the entities of these IDs only, rather than obtaining all from the API
<startTime> (required): Start time to collect metrics (will be rounded backwards to the whole hour, adjust to local full day for DAY granularity)
<endTime> (optional): Optionally limit data to the specified timestamp
<preview> (optional): Preview the data and limit API calls to 1
<target_table> (optional): Target table to save data
<sync> (optional): Use the synchronous API
<delete_last_days> (optional): Delete last x days, where x =0..30, but not deeper than 37 days ago from now and not deeper than startTime will be deleted

Example

CREATE VIEW twitter_examples.example_Analytics AS
	SELECT * FROM (
		CALL twitter.Analytics(
			accountId => '18ce53ylipy'/* Mandatory: Twitter Account ID */,
			periodDuration => 45/* Mandatory: Duration of a single batch: max 45 for HOUR, and 90 for DAY/TOTAL */,
			twitterEntityType => 'PROMOTED_TWEET'/* Mandatory: Entity type: ACCOUNT, CAMPAIGN, LINE_ITEM, or PROMOTED_TWEET */,
			granularity => 'HOUR'/* Mandatory: Metrics granularity: HOUR, DAY, or TOTAL */,
			withDeleted => true/* Optional: Include deleted items (only applicable when entityIds is null, otherwise ignored) */,
			twitterSegmentationType => 'GENDER'/* Optional: Segmentation type */,
			idPortion => 20/* Optional: How many IDs to query at the same time, default 20 */,
			entityIds => null/* Optional: Request data for the entities of these IDs only, rather than obtaining all from the API */,
			startTime => '2016-07-01 07:00:00'/* Mandatory: Start time to collect metrics (will be rounded backwards to the whole hour, adjust to local full day for DAY granularity) */,
			endTime => '2016-07-30 07:00:00'/* Optional: Optionally limit data to the specified timestamp */,
			preview => true/* Optional: Preview the data and limit API calls to 1 */,
			target_table => null/* Optional: Target table to save data */
		)
	) x

DownloadAnalytics

Download all Twitter Ads Analytics (metrics)
Parameter
<startTime> (required): Start time
<accountId> (optional): The identifier for the leveraged account
<twitterEntityType> (required): Entity type: ACCOUNT, CAMPAIGN, LINE_ITEM, or PROMOTED_TWEET
<granularity> (required): Metrics granularity: HOUR, DAY, or TOTAL
<periodDuration> (optional): Batch duration
<withDeleted> (optional): Include deleted items (only applicable when entityIds is null, otherwise ignored)
<twitterSegmentationType> (optional): Segmentation type
<idPortion> (optional): How many IDs to query at the same time, default 20
<preview> (optional): Preview the data and limit API calls to 1
<target_table> (optional): Fully-qualified table name to store the data
<sync> (optional): Use the synchronous API
<delete_last_days> (optional): Delete last x days, where x =0..30, but not deeper than 37 days ago from now and not deeper than startTime will be deleted

NonPublicMetrics

Non-public metrics
Parameter
<tweet_table> (optional): Table name with tweet data
<target_table> (optional): Table name to save the data to
<preview> (optional): Preview only, don't write into table
<label> (optional): Multi-tenancy label

Example

CREATE VIEW twitter_examples.example_NonPublicMetrics AS
	SELECT * FROM (
		CALL twitter.NonPublicMetrics(
			preview => true/* Optional: Preview the data and limit API calls to 1 */,
			target_table => null/* Optional: Target table to save data */
		)
	) x

PublicMetrics

Public metrics
Parameter
<tweet_table> (optional): Table name with tweet data
<target_table> (optional): Table name to save the data to
<preview> (optional): Preview only, don't write into table
<label> (optional): Multi-tenancy label

Example

CREATE VIEW twitter_examples.example_PublicMetrics AS
	SELECT * FROM (
		CALL twitter.PublicMetrics(
			preview => true/* Optional: Preview the data and limit API calls to 1 */,
			target_table => null/* Optional: Target table to save data */
		)
	) x

createAsyncJob

Create an asynchronous analytics job for the current account
Parameter
<accountId> (required): The identifier for the leveraged account
<twitterEntityType> (required): The entity type to retrieve data for. Possible values: ACCOUNT, CAMPAIGN, FUNDING_INSTRUMENT, LINE_ITEM, ORGANIC_TWEET, PROMOTED_TWEET
<ids> (required): The specific entities to retrieve data for. Specify a comma-separated list of entity IDs
<startTime> (required): Scopes the retrieved data to the specified start time
<endTime> (required): Scopes the retrieved data to the specified end time
<granularity> (required): Specify how granular the retrieved data should be
<placement> (optional): Scopes the retrieved data to a particular placement. Possible values: ALL_ON_TWITTER, PUBLISHER_NETWORK
<twitterSegmentationType> (optional): Specify how the retrieved data should be segmented
<label> (optional): Multi-tenancy label

getAllAccounts

Advertising-enabled accounts the authenticating user has access to
Parameter
<accountIds> (optional): Scope the response to just the desired account IDs by specifying a comma-separated list of identifiers
<sortBy> (optional): Sorts by supported attribute in ascending or descending order
<withDeleted> (optional): Include deleted results in your request
<target_table> (optional): Table name to save the data to
<preview> (optional): Preview only, don't write into table
<label> (optional): Multi-tenancy label

Example

CREATE VIEW twitter_examples.example_getAllAccounts AS
	SELECT * FROM (
		CALL twitter.getAllAccounts(
			withDeleted => true,
			preview => true
		)
	) x

getAllCampaigns

Campaigns associated with accounts
Parameter
<accountId> (optional): The identifier for the leveraged account
<campaignIds> (optional): Scope the response to just the desired campaigns by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided
<withDraft> (optional): Scope the response to just line items under draft campaigns
<fundingInstrumentIds> (optional): Scope the response to just the campaigns under specific funding instruments by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided
<sortBy> (optional): Sorts by supported attribute in ascending or descending order
<withDeleted> (optional): Include deleted results in your request
<target_table> (optional): Table name to save the data to
<preview> (optional): Preview only, don't write into table
<label> (optional): Multi-tenancy label

Example

CREATE VIEW twitter_examples.example_getAllCampaigns AS
	SELECT * FROM (
		CALL twitter.getAllCampaigns(
			accountId => null/* Optional: The identifier for the leveraged account. */,
			campaignIds => null/* Optional: A string of comma-separated values. Scope the response to just the desired campaigns by specifying a commaseparated list of identifiers. Up to 50 ids may be provided. */,
			fundingInstrumentIds => null/* Optional: A string of comma-separated values. Scope the response to just the desired funding instruments by specifying a commaseparated list of identifiers. */,
			withDeleted => true/* Mandatory: Include deleted results in your request. */,
			preview => true
		)
	) x

getAllFundingInstruments

Funding instruments associated with accounts
Parameter
<accountId> (optional): The identifier for the leveraged account
<fundingInstrumentIds> (optional): Scope the response to just the line items under specific funding instruments by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided
<sortBy> (optional): Sorts by supported attribute in ascending or descending order
<withDeleted> (optional): Include deleted results in your request
<target_table> (optional): Table name to save the data to
<preview> (optional): Preview only, don't write into table
<label> (optional): Multi-tenancy label

Example

CREATE VIEW twitter_examples.example_getAllFundingInstruments AS
	SELECT * FROM (
		CALL twitter.getAllFundingInstruments(
			accountId => null/* Optional: The identifier for the leveraged account. */,
			withDeleted => true/* Mandatory: Include deleted results in your request. */,
			fundingInstrumentIds => null/* Optional: A string of comma-separated values. Scope the response to just the desired funding instruments by specifying a Collection of identifiers. Up to 50 ids may be provided. */,
			sortBy=> null /* Optional: Possible values [CREATED_AT_ASC,UPDATED_AT_ASC,DELETED_ASC,FUNDED_AMOUNT_LOCAL_MICRO_ASC,START_TIME_ASC,END_TIME_ASC,CREATED_AT_DESC,UPDATED_AT_DESC,DELETED_DESC,FUNDED_AMOUNT_LOCAL_MICRO_DESC,START_TIME_DESC,END_TIME_DESC]. Sorts by supported attribute in ascending or descending order. */,
			preview => true
		)
	) x

getAllLineItems

Line items associated with the accounts
Parameter
<accountId> (optional): The identifier for the leveraged account
<campaignIds> (optional): Scope the response to just the line items under specific campaigns by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided
<withDraft> (optional): Scope the response to just line items under draft campaigns
<fundingInstrumentIds> (optional): Scope the response to just the line items under specific funding instruments by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided
<lineItemIds> (optional): Scope the response to just the desired line items by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided
<sortBy> (optional): Sorts by supported attribute in ascending or descending order
<withDeleted> (optional): Include deleted results in your request
<target_table> (optional): Table name to save the data to
<preview> (optional): Preview only, don't write into table
<label> (optional): Multi-tenancy label

Example

CREATE VIEW twitter_examples.example_getAllLineItems AS
	SELECT * FROM (
		CALL twitter.getAllLineItems(
			accountId => null/* Optional: The identifier for the leveraged account. */,
			campaignIds => null/* Optional: A string of comma-separated values. Scope the response to just the desired campaigns by specifying a Collection of identifiers. Up to 50 ids may be provided. */,
			lineItemIds => null/* Optional: A string of comma-separated values. Scope the response to just the desired line items by specifying a Collection of identifiers. Up to 50 ids may be provided. */,
			fundingInstrumentIds => null/* Optional: A string of comma-separated values. Scope the response to just the desired funding instruments by specifying a Collection of identifiers. Up to 50 ids may be provided. */,
			withDeleted => true/* Mandatory: Include deleted results in your request. */,
			preview => true
		)
	) x

getAllMediaCreatives

Tweets associated with line items under the accounts
Parameter
<accountId> (optional): The identifier for the leveraged account
<lineItemIds> (optional): Scope the response to just the Tweets associated with specific line items by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided
<campaignId> (optional):
<mediaCreativeIds> (optional): Scope the response to just the desired media creatives by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided
<sortBy> (optional): Sorts by supported attribute in ascending or descending order
<withDeleted> (optional): Include deleted results in your request
<target_table> (optional): Table name to save the data to
<preview> (optional): Preview only, don't write into table
<label> (optional): Multi-tenancy label

getAllPromotedTweets

Tweets associated with line items under the accounts
Parameter
<accountId> (optional): The identifier for the leveraged account
<lineItemIds> (optional): Scope the response to just the Tweets associated with specific line items by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided
<promotedTweetIds> (optional): Scope the response to just the desired promoted Tweets by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided
<sortBy> (optional): Sorts by supported attribute in ascending or descending order
<withDeleted> (optional): Include deleted results in your request
<target_table> (optional): Table name to save the data to
<preview> (optional): Preview only, don't write into table
<label> (optional): Multi-tenancy label

Example

CREATE VIEW twitter_examples.example_getAllPromotedTweets AS
	SELECT * FROM (
		CALL twitter.getAllPromotedTweets(
			accountId => null/* Optional: The identifier for the leveraged account. */,
			withDeleted => true/* Mandatory: Include deleted results in your request. */,
			preview => true
		)
	) x

getAnalyticsSync

Returns analytics data in synchronous way
Parameter
<accountId> (required): The identifier for the leveraged account
<twitterEntityType> (required): The entity type to retrieve data for. Possible values: ACCOUNT, CAMPAIGN, FUNDING_INSTRUMENT, LINE_ITEM, ORGANIC_TWEET, PROMOTED_TWEET
<ids> (required): The specific entities to retrieve data for. Specify a comma-separated list of entity IDs
<startTime> (required): Scopes the retrieved data to the specified start time
<endTime> (required): Scopes the retrieved data to the specified end time
<granularity> (required): Specify how granular the retrieved data should be
<placement> (optional): Scopes the retrieved data to a particular placement. Possible values: ALL_ON_TWITTER, PUBLISHER_NETWORK
<twitterSegmentationType> (optional): Specify how the retrieved data should be segmented
<label> (optional): Multi-tenancy label

getFollowers

Followers
Parameter
<user_id> (optional): The ID of the user for whom to return results
<screen_name> (optional): The screen name of the user for whom to return results
<target_table> (optional): Table name to save the data to
<preview> (optional): Preview only, don't write into table
<label> (optional): Multi-tenancy label

Example

CREATE VIEW twitter_examples.example_getFollowers AS
	SELECT * FROM (
		CALL twitter.getFollowers(
			preview => true/* Optional: Preview the data and limit API calls to 1 */,
			target_table => null/* Optional: Target table to save data */
		)
	) x

getJobExecutionDetails

Retrieve details for some or all asynchronous analytics jobs for the current account
Parameter
<accountId> (required): The identifier for the leveraged account
<jobIds> (required): Scope the response to just the desired jobs by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided
<label> (optional): Multi-tenancy label

getTimeline

Most recent Tweets posted by the user indicated by the screen_name or user_id parameters, or home timeline, or mentions timeline
Parameter
<user_id> (optional): The ID of the user for whom to return results
<screen_name> (optional): The screen name of the user for whom to return results
<mentions> (optional): Returns the most recent mentions (Tweets containing a users's @screen_name) for the authenticating user
<home> (optional): Returns a collection of the most recent Tweets and Retweets posted by the authenticating user and the users they follow
<exclude_replies> (optional): This parameter will prevent replies from appearing in the returned timeline
<include_rts> (optional): When set to false , the timeline will strip any native retweets (though they will still count toward both the maximal length of the timeline and the slice selected by the count parameter)
<since_id> (optional): Returns results with an ID greater than (that is, more recent than) the specified ID
<target_table> (optional): Table name to save the data to
<preview> (optional): Preview only, don't write into table
<label> (optional): Multi-tenancy label

Example

CREATE VIEW twitter_examples.example_getTimeline AS
	SELECT * FROM (
		CALL twitter.getTimeline(
			user_id => null,
			screen_name => 'DataVirtuality',
			mentions => null,
			home => null,
			exclude_replies => false,
			include_rts => true,
			target_table => null,
			preview => true
		)
	)x

getUsers

Fully-hydrated user objects for up to 100 users per request
Parameter
<user_id> (optional): The ID of the user for whom to return results
<screen_name> (optional): The screen name of the user for whom to return results
<label> (optional): Multi-tenancy label