分析

异步分析

在 Postman 中运行 ❯

GET stats/jobs/accounts/:account_id

检索当前账号的部分或所有异步分析作业的详细信息。

作业成功完成 ("status": "SUCCESS") 后，就可以通过下载 url 参数中返回的 URL 中的文件来检索数据。为了优化传输，这些结果文件经过压缩 (gzip)，在访问之前必须解压缩。

注意：此端点返回以下 HTTP 响应标头。

  • X-Concurrent-Job-Limit：在任何给定时间可处于某个处理状态的最大作业数。
  • X-Concurrent-Job-Limit-Remaining：可以创建的作业数量，由当前正在处理的作业数量决定。

资源 URL

https://ads-api.twitter.com/10/stats/jobs/accounts/:account_id

参数

名称 说明
account_id
必需

所使用账号的标识符。出现在资源路径中，通常是所有广告商 API 请求的必要参数，不包含 GET accounts。指定账号必须与已验证的用户关联。

类型：string

示例：18ce54d4x5t
count
可选

指定每个不同请求尝试检索的记录数量。

类型：int

默认值：200
最小值、最大值：1、1000
cursor
可选

指定光标以获取下一页结果。参阅分页了解更多信息。

类型：string

示例：8x7v00oow
job_ids
可选

通过指定以逗号分隔的标识符列表将响应范围限定为所需的作业。最多可提供 200 个 ID。

类型：long

示例：883787505404747776

请求示例

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

响应示例

{
  "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",
      "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",
      "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

为当前账号创建异步分析作业。

非细分查询允许的最大时间范围 (end_time - start_time) 为 90 天。对于细分查询，最大时间范围为 45 天。

返回 job_id，可用于 GET stats/jobs/accounts/:account_id 请求中来查看作业完成处理的时间。

作业成功完成 ("status": "SUCCESS") 后，就可以通过下载 url 参数中返回的 URL 中的文件来检索数据。为了优化传输，这些结果文件经过压缩 (gzip)，在访问之前必须解压缩。

注意：此端点返回以下 HTTP 响应标头。

  • X-Concurrent-Job-Limit：在任何给定时间可处于某个处理状态的最大作业数。
  • X-Concurrent-Job-Limit-Remaining：可以创建的作业数量，由当前正在处理的作业数量决定。

资源 URL

https://ads-api.twitter.com/10/stats/jobs/accounts/:account_id

参数

名称 说明
account_id
必需

所使用账号的标识符。出现在资源路径中，通常是所有广告商 API 请求的必要参数，不包含 GET accounts。指定账号必须与已验证的用户关联。

类型：string

示例：18ce54d4x5t
end_time
必需

使用以 ISO 8601 表示的指定结束时间限定检索数据的范围。

注意：必须以整小时数（0 分 0 秒）表示。

类型：string

示例：2017-05-26T07:00:00Z
entity
必需

要检索数据的实体类型。

类型：enum

可能值：ACCOUNT、CAMPAIGN、FUNDING_INSTRUMENT、LINE_ITEM、ORGANIC_TWEET、PROMOTED_ACCOUNT、PROMOTED_TWEET、MEDIA_CREATIVE
entity_ids
必需

要检索数据的特定实体。指定以逗号分隔的实体 ID 列表。

注意：最多可提供 20 个实体 ID。

类型：string

示例：8u94t
granularity
必需

指定检索数据的粒度。

类型：enum

可能值：DAY、HOUR、TOTAL
metric_groups
必需

应该返回的特定指标。指定以逗号分隔的指标组列表。有关详情，请参见指标与细分。

注意：MOBILE_CONVERSION 数据应单独请求。

类型：enum

可能值：BILLING、ENGAGEMENT、LIFE_TIME_VALUE_MOBILE_CONVERSION、MEDIA、MOBILE_CONVERSION、VIDEO、WEB_CONVERSION
placement
必需

将检索到的数据限定到特定位置。

注意：每个请求只接受一个值。对于同时具有 Twitter 和 Twitter 受众平台位置的实体，需要单独发出请求，每个位置值对应一个请求。

类型：enum

可能值：ALL_ON_TWITTER、PUBLISHER_NETWORK
start_time
必需

使用以 ISO 8601 表示的指定开始时间限定检索数据的范围。

注意：必须以整小时数（0 分 0 秒）表示。

类型：string

示例：2017-05-19T07:00:00Z
country
有时为必需

国家/地区。这是 GET targeting_criteria/locations 端点响应中的 targeting_value。

注意：如果 segmentation_type 为 METROS、POSTAL_CODES 或 REGIONS，则为必填。

类型：string

示例：96683cc9126741d1
platform
有时为必需

平台类型。

注意：如果 segmentation_type 为 DEVICES 或 PLATFORM_VERSIONS，则为必填。

类型：int

示例：请参见 GET targeting_criteria/platforms
segmentation_type
可选

指定检索到的数据的细分方式。

注意：每个请求只接受一个值。

注意：在请求分析媒体素材或原始推文时不支持细分。

类型：enum

可能值：请参见指标与细分。

请求示例

POST https://ads-api.twitter.com/10/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

响应示例

{
  "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

为给定广告账号取消异步分析作业。

注意：只能取消 PROCESSING 项作业。

资源 URL

https://ads-api.twitter.com/10/stats/jobs/accounts/:account_id/:job_id

参数

名称 说明
account_id
必需

所使用账号的标识符。出现在资源路径中，通常是所有广告商 API 请求的必要参数，不包含 GET accounts。指定账号必须与已验证的用户关联。

类型：string

示例：18ce54d4x5t
job_id
必需

请求中对正在操作的作业的引用。

类型：long

示例：823634888955809793

请求示例

DELETE https://ads-api.twitter.com/10/stats/jobs/accounts/18ce54d4x5t/823634888955809793

响应示例

{
  "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,
    "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"
    ]
  }
}