Asynchronous Analytics
asynchronous

Asynchronous Analytics

Run in Postman ❯ 

GET stats/jobs/accounts/:account_id

Retrieve details for some or all asynchronous analytics jobs for the current account.

Once a job has successfully completed ("status": "SUCCESS"), data can be retrieved by downloading the file in the URL returned in the url parameter. These result files are compressed (gzip) to optimize transfer and must be uncompressed before access.

Note: This endpoint returns the following HTTP response headers.

  • X-Concurrent-Job-Limit: The maximum number of jobs that may be in a processing state at any given time.
  • X-Concurrent-Job-Limit-Remaining: The number of jobs that can be created given the number currently being processed.

Resource URL

https://ads-api.x.com/12/stats/jobs/accounts/:account_id

Parameters

Name Description
account_id
required

The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user.

Type: string

Example: 18ce54d4x5t
count
optional

Specifies the number of records to try and retrieve per distinct request.

Type: int

Default: 200
Min, Max: 1, 1000
cursor
optional

Specifies a cursor to get the next page of results. See Pagination for more information.

Type: string

Example: 8x7v00oow
job_ids
optional

Scope the response to just the desired jobs by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.

Type: string

Example: 883787505404747776

Example Request

GET https://ads-api.x.com/12/stats/jobs/accounts/18ce54d4x5t?job_ids=883787505404747776

Example Response

{
  "request": {
    "params": {
      "job_ids": [
        "883787505404747776"
      ],
      "account_id": "18ce54d4x5t"
    }
  },
  "next_cursor": null,
  "data": [
    {
      "start_time": "2017-05-19T07:00:00Z",
      "segmentation_type": null,
      "url": "https://ton.twimg.com/advertiser-api-async-analytics/hMk_CPWYqCAYY99gWzylwNJe26HgVm9Iji0wFiuEXbE74bjWsyTtop49MpL-QXO5bhebBZwFhvK9GyNs4gSnfoCG8wdSLmnhKZ0hj7PezoiQggj9AywMDHCMwq3gGHHv.json.gz",
      "entity_ids": [
        "8u94t"
      ],
      "end_time": "2017-05-26T07:00:00Z",
      "country": null,
      "placement": "ALL_ON_TWITTER",
      "id": "883787505404747776",
      "expires_at": "2017-07-10T20:38:57Z",
      "status": "SUCCESS",
      "granularity": "DAY",
      "entity": "LINE_ITEM",
      "created_at": "2017-07-08T20:38:55Z",
      "platform": null,
      "updated_at": "2017-07-08T20:38:57Z",
      "metric_groups": [
        "ENGAGEMENT"
      ]
    }
  ]
}

POST stats/jobs/accounts/:account_id

Create an asynchronous analytics job for the current account.

A maximum time range (end_time - start_time) of 90 days is allowed for non-segmented queries. For segmented queries, the maximum time range is 45 days.

A job_id is returned, which can be used in GET stats/jobs/accounts/:account_id requests to check when the job has finished processing.

Once a job has successfully completed ("status": "SUCCESS"), data can be retrieved by downloading the file in the URL returned in the url parameter. These result files are compressed (gzip) to optimize transfer and must be uncompressed before access.

Note: This endpoint returns the following HTTP response headers.

  • X-Concurrent-Job-Limit: The maximum number of jobs that may be in a processing state at any given time.
  • X-Concurrent-Job-Limit-Remaining: The number of jobs that can be created given the number currently being processed.

Resource URL

https://ads-api.x.com/12/stats/jobs/accounts/:account_id

Parameters

Name Description
account_id
required

The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user.

Type: string

Example: 18ce54d4x5t
end_time
required

Scopes the retrieved data to the specified end time, expressed in ISO 8601.

Note: Must be expressed in whole hours (0 minutes and 0 seconds).

Type: string

Example: 2017-05-26T07:00:00Z
entity
required

The entity type to retrieve data for.

Type: enum

Possible values: ACCOUNT, CAMPAIGN, FUNDING_INSTRUMENT, LINE_ITEM, ORGANIC_TWEET, PROMOTED_ACCOUNT, PROMOTED_TWEET, MEDIA_CREATIVE
entity_ids
required

The specific entities to retrieve data for. Specify a comma-separated list of entity IDs.

Note: Up to 20 entity IDs may be provided.

Type: string

Example: 8u94t
granularity
required

Specify how granular the retrieved data should be.

Type: enum

Possible values: DAY, HOUR, TOTAL
metric_groups
required

The specific metrics that should be returned. Specify a comma-separated list of metric groups. For more information see Metrics and Segmentation.

Note: MOBILE_CONVERSION data should be requested separately.

Type: enum

Possible values: BILLING, ENGAGEMENT, LIFE_TIME_VALUE_MOBILE_CONVERSION, MEDIA, MOBILE_CONVERSION, VIDEO, WEB_CONVERSION
placement
required

Scopes the retrieved data to a particular placement.

Note: Only a single value accepted per request. For entities with both Twitter and Twitter Audience Platform placement, separate requests are required, one for each placement value.

Type: enum

Possible values: ALL_ON_TWITTER, PUBLISHER_NETWORK
start_time
required

Scopes the retrieved data to the specified start time, expressed in ISO 8601.

Note: Must be expressed in whole hours (0 minutes and 0 seconds).

Type: string

Example: 2017-05-19T07:00:00Z
country
sometimes required

The country. This is the targeting_value from the GET targeting_criteria/locations endpoint response.

Note: Required if segmentation_type is either METROS, POSTAL_CODES, or REGIONS.

Type: string

Example: 96683cc9126741d1
platform
sometimes required

The platform type.

Note: Required if segmentation_type is either DEVICES or PLATFORM_VERSIONS.

Type: int

Example: See GET targeting_criteria/platforms
segmentation_type
optional

Specify how the retrieved data should be segmented.

Note: Only a single value accepted per request.

Note: Segmentation not supported when requesting analytics for Media Creatives or organic Tweets.

Type: enum

Possible values: See Metrics and Segmentation.

Example Request

POST https://ads-api.x.com/12/stats/jobs/accounts/18ce54d4x5t?entity=LINE_ITEM&entity_ids=8u94t&start_time=2017-05-19&end_time=2017-05-26&granularity=DAY&placement=ALL_ON_TWITTER&metric_groups=ENGAGEMENT

Example Response

{
  "request": {
    "params": {
      "start_time": "2017-05-19T07:00:00Z",
      "entity_ids": [
        "8u94t"
      ],
      "account_id": "18ce54d4x5t",
      "end_time": "2017-05-26T07:00:00Z",
      "placement": "ALL_ON_TWITTER",
      "granularity": "DAY",
      "entity": "LINE_ITEM",
      "metric_groups": [
        "ENGAGEMENT"
      ]
    }
  },
  "data": {
    "start_time": "2017-05-19T07:00:00Z",
    "segmentation_type": null,
    "url": null,
    "id_str": "883787505404747776",
    "entity_ids": [
      "8u94t"
    ],
    "end_time": "2017-05-26T07:00:00Z",
    "country": null,
    "placement": "ALL_ON_TWITTER",
    "id": 883787505404747776,
    "expires_at": null,
    "status": "PROCESSING",
    "granularity": "DAY",
    "entity": "LINE_ITEM",
    "created_at": "2017-07-08T20:38:55Z",
    "platform": null,
    "updated_at": "2017-07-08T20:38:55Z",
    "metric_groups": [
      "ENGAGEMENT"
    ]
  }
}

DELETE stats/jobs/accounts/:account_id/:job_id

Cancel an asynchronous analytics job for a given ads account.

Note: Only PROCESSING jobs can be cancelled.

Resource URL

https://ads-api.x.com/12/stats/jobs/accounts/:account_id/:job_id

Parameters

Name Description
account_id
required

The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user.

Type: string

Example: 18ce54d4x5t
job_id
required

A reference to the job you are operating with in the request.

Type: string

Example: 823634888955809793

Example Request

DELETE https://ads-api.x.com/12/stats/jobs/accounts/18ce54d4x5t/823634888955809793

Example Response

{
  "request": {
    "params": {
      "job_id": "823634888955809793",
      "account_id": "18ce54d4x5t"
    }
  },
  "data_type": "job",
  "data": {
    "start_time": "2016-10-25T07:00:00Z",
    "segmentation_type": "AGE",
    "url": null,
    "entity_ids": [
      "6c62d"
    ],
    "end_time": "2016-12-05T08:00:00Z",
    "country": null,
    "placement": "ALL_ON_TWITTER",
    "id": "823634888955809793",
    "expires_at": null,
    "status": "CANCELLED",
    "granularity": "DAY",
    "entity": "LINE_ITEM",
    "created_at": "2017-01-23T20:53:54Z",
    "platform": null,
    "updated_at": "2017-01-23T20:53:54Z",
    "metric_groups": [
      "ENGAGEMENT"
    ]
  }
}