Analytics
Asynchronous Analytics¶
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.
Resource URL¶
https://ads-api.twitter.com/4/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: |
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: |
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: long Example: |
Example Request¶
GET https://ads-api.twitter.com/4/stats/jobs/accounts/18ce54d4x5t?job_ids=883787505404747776
Example Response¶
{
"request": {
"params": {
"job_ids": [
883787505404747776
]
}
},
"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",
"id_str": "883787505404747776",
"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",
"account_id": "18ce54d4x5t",
"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.
Resource URL¶
https://ads-api.twitter.com/4/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: |
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: |
entity
required
|
The entity type to retrieve data for. Type: enum Possible values: |
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: |
granularity
required
|
Specify how granular the retrieved data should be. Type: enum Possible values: |
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: Type: enum Possible values: |
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: |
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: |
country
sometimes required
|
The country. Note: Required if Type: string Example: See GET targeting_criteria/locations |
platform
sometimes required
|
The platform type. Note: Required if Type: int Example: See GET targeting_criteria/platforms |
segmentation_type
optional
|
Specify how the retrieved data should be segmented. Type: enum Possible values: See Metrics and Segmentation. |
Example Request¶
POST https://ads-api.twitter.com/4/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"
],
"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,
"account_id": "18ce54d4x5t",
"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.twitter.com/4/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: |
job_id
required
|
A reference to the job you are operating with in the request. Type: long Example: |
Example Request¶
DELETE https://ads-api.twitter.com/4/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,
"id_str": "823634888955809793",
"entity_ids": [
"6c62d"
],
"end_time": "2016-12-05T08:00:00Z",
"country": null,
"placement": "ALL_ON_TWITTER",
"id": 823634888955809793,
"expires_at": null,
"account_id": "18ce54d4x5t",
"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"
]
}
}