> ## Documentation Index
> Fetch the complete documentation index at: https://generaltranslation.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Usage API

> Usage API は、エンタープライズアカウントに紐づく各種プロダクトにおける利用量に、プログラムからアクセスし可視化できる無料の REST API です。

<div id="usage-api-twitter-api">
  ## 利用状況 API | Twitter API
</div>

<div id="overview">
  ### 概要
</div>

`Enterprise`

これは、アカウント配下のさまざまな API における利用状況を監視および管理するための、最も重要かつ *最適な* ツールです。

**重要な免責事項:**

Usage API から返される利用量は、トライアルやその他の請求調整により、請求書に記載される数値と一致しない場合があります。すべての数値は、ある 1 日 (UTC) に消費された重複排除済みのアクティビティに基づいています。

<div id="features">
  #### 機能
</div>

* console.gnip.com の UI で利用可能な使用状況データをプログラムで取得
* ストリームレベルの使用状況データ - プロダクトレベルに加え、ストリームレベル (例: dev と prod) での使用状況データを提供
* きめ細かくわかりやすいデータ - 検索の「requests」は Full-Archive と 30-Day Search 各プロダクトごとに区分
* PowerTrack の履歴「days」と「jobs」 

<div id="supported-apis">
  ### 対応している API
</div>

以下は、Usage API が現在サポートしている API のリストです。

* PowerTrack API `enterprise`
* 30-Day Search API `enterprise`
* Full-Archive Search API `enterprise`
* Historical PowerTrack `enterprise`

<div id="limitations">
  ### 制限事項
</div>

* Usage API を使用すると、2018 年 5 月 1 日以降の利用状況データにアクセスできます。2019 年 7 月 1 日以降は、Usage API を使用して、**直近 13 か月間の各暦月分** の利用状況データにアクセスできます。

* `fromDate` と `toDate` で定義される **3 か月間の期間** ごとに、利用状況データにアクセスできます。

以下にリクエストとレスポンスの例を示します。

```bash theme={null}
curl -u<username>:<password> \
"https://gnip-api.x.com/metrics/usage/accounts/<account-name>.json?bucket=month"
```

```json theme={null}
{
  "account": {
    "name": "accountnamehere"
  },
  "publishers": [
    {
      "type": "twitter",
      "used": [
        {
          "timePeriod": "201805010000",
          "activities": 1235,
          "searchRequests30Day": 3,
          "searchRequestsFullArchive": 19,
          "historicalPowertrackDays": 0,
          "historicalPowertrackJobs": 0
        },
        {
          "timePeriod": "201806010000",
          "activities": 23467,
          "searchRequests30Day": 0,
          "searchRequestsFullArchive": 66,
          "historicalPowertrackDays": 0,
          "historicalPowertrackJobs": 0
        },
        {
          "timePeriod": "201807010000",
          "activities": 431,
          "searchRequests30Day": 11,
          "searchRequestsFullArchive": 4,
          "historicalPowertrackDays": 0,
          "historicalPowertrackJobs": 0
        }
      ],
      "projected": {
        "timePeriod": "201807010000",
        "activities": 803,
        "searchRequests30Day": 20,
        "searchRequestsFullArchive": 7,
        "historicalPowertrackDays": 0,
        "historicalPowertrackJobs": 0
      },
      "products": [
        {
          "type": "Historical PowerTrack サブスクリプション",
          "used": [
            {
              "timePeriod": "201805010000",
              "activities": 0,
              "days": 0,
              "jobs": 0
            },
            {
              "timePeriod": "201806010000",
              "activities": 0,
              "days": 0,
              "jobs": 0
            },
            {
              "timePeriod": "201807010000",
              "activities": 0,
              "days": 0,
              "jobs": 0
            }
          ],
          "projected": {
            "timePeriod": "201807010000",
            "activities": 0,
            "days": 0,
            "jobs": 0
          }
        },
        {
          "type": "PowerTrack",
          "used": [
            {
              "timePeriod": "201805010000",
              "activities": 267
            },
            {
              "timePeriod": "201806010000",
              "activities": 3
            },
            {
              "timePeriod": "201807010000",
              "activities": 32
            }
          ],
          "projected": {
            "timePeriod": "201807010000",
            "activities": 59
          },
          "endpoints": [
            {
              "type": "PowerTrack 2.0",
              "label": "actformat",
              "used": [
                {
                  "timePeriod": "201805010000",
                  "activities": 0
                },
                {
                  "timePeriod": "201806010000",
                  "activities": 0
                },
                {
                  "timePeriod": "201807010000",
                  "activities": 0
                }
              ],
              "projected": {
                "timePeriod": "201807010000",
                "activities": 0
              }
            },
              {
              "type": "PowerTrack Replay 2.0",
              "label": "ogformat",
              "used": [
                {
                  "timePeriod": "201805010000",
                  "activities": 0
                },
                {
                  "timePeriod": "201806010000",
                  "activities": 0
                },
                {
                  "timePeriod": "201807010000",
                  "activities": 0
                }
              ],
              "projected": {
                "timePeriod": "201807010000",
                "activities": 0
              }
            }
          ]
        },
        {
          "type": "Search API（30日間）2.0",
          "used": [
            {
              "timePeriod": "201805010000",
              "activities": 10,
              "searchRequests30Day": 3
            },
            {
              "timePeriod": "201806010000",
              "activities": 0,
              "searchRequests30Day": 0
            },
            {
              "timePeriod": "201807010000",
              "activities": 23,
              "searchRequests30Day": 11
            }
          ],
          "projected": {
            "timePeriod": "201807010000",
            "activities": 42,
            "searchRequests30Day": 20
          },
          "endpoints": [
            {
              "type": "Search API（30日間）2.0",
              "label": "ogformat",
              "used": [
                {
                  "timePeriod": "201805010000",
                  "activities": 10,
                  "searchRequests30Day": 3
                },
                {
                  "timePeriod": "201806010000",
                  "activities": 0,
                  "searchRequests30Day": 0
                },
                {
                  "timePeriod": "201807010000",
                  "activities": 21,
                  "searchRequests30Day": 10
                }
              ],
              "projected": {
                "timePeriod": "201807010000",
                "activities": 39,
                "searchRequests30Day": 18
              }
            }
          ]
        },
        {
          "type": "Search API（全アーカイブ）",
          "used": [
            {
              "timePeriod": "201805010000",
              "activities": 961,
              "searchRequestsFullArchive": 19
            },
            {
              "timePeriod": "201806010000",
              "activities": 23466,
              "searchRequestsFullArchive": 66
            },
            {
              "timePeriod": "201807010000",
              "activities": 379,
              "searchRequestsFullArchive": 4
            }
          ],
          "projected": {
            "timePeriod": "201807010000",
            "activities": 706,
            "searchRequestsFullArchive": 7
          },
          "endpoints": [
            {
              "type": "Search API（全アーカイブ）",
              "label": "actformat",
              "used": [
                {
                  "timePeriod": "201805010000",
                  "activities": 1,
                  "searchRequestsFullArchive": 3
                },
                {
                  "timePeriod": "201806010000",
                  "activities": 0,
                  "searchRequestsFullArchive": 0
                },
                {
                  "timePeriod": "201807010000",
                  "activities": 2,
                  "searchRequestsFullArchive": 1
                }
              ],
              "projected": {
                "timePeriod": "201807010000",
                "activities": 3,
                "searchRequestsFullArchive": 1
              }
            },
            {
              "type": "Search API（全アーカイブ）",
              "label": "ogformat",
              "used": [
                {
                  "timePeriod": "201805010000",
                  "activities": 961,
                  "searchRequestsFullArchive": 16
                },
                {
                  "timePeriod": "201806010000",
                  "activities": 23466,
                  "searchRequestsFullArchive": 66
                },
                {
                  "timePeriod": "201807010000",
                  "activities": 379,
                  "searchRequestsFullArchive": 3
                }
              ],
              "projected": {
                "timePeriod": "201807010000",
                "activities": 706,
                "searchRequestsFullArchive": 5
              }
            }
          ]
        }
      ]
    }
  ],
  "bucket": "month",
  "fromDate": "201805010000",
  "toDate": "201808010000"
}
```

<div id="sample-payload">
  ### ペイロードのサンプル
</div>

以下はペイロードの例です。

```bash theme={null}
{
  "account": {
    "name": "gnip-username"
  },
  "bucket": "month",
  "publishers": [
    {
      "type": "automattic",
      "used": [
        {
          "activities": 0,
          "timePeriod": "201603010000"
        }
      ],
      "projected": {
        "activities": 0,
        "timePeriod": "201603010000"
      },
      "products": [
        {
          "type": "PowerTrack",
          "used": [
            {
              "timePeriod": "201603010000",
              "activities": 0
            }
          ],
          "projected": {
            "timePeriod": "201603010000",
            "activities": 0
          },
          "endpoints": [
            {
              "type": "PowerTrack",
              "label": "dev",
              "used": [
                {
                  "timePeriod": "201603010000",
                  "activities": 0
                }
              ],
              "projected": {
                "timePeriod": "201603010000",
                "activities": 0
              }
            }
          ]
        }
      ]
    },
    {
      "type": "twitter",
      "used": [
        {
          "activities": 84,
          "searchRequests30Day": 4,
          "searchRequestsFullArchive": 0,
          "historicalPowertrackDays": 0,
          "historicalPowertrackJobs": 0,
          "timePeriod": "201603010000"
        }
      ],
      "projected": {
        "activities": 0,
        "searchRequests30Day": 0,
        "searchRequestsFullArchive": 0,
        "historicalPowertrackDays": 0,
        "historicalPowertrackJobs": 0,
        "timePeriod": "201601010000"
      },
      "products": [
        {
          "type": "Historical PowerTrack 2.0",
          "used": [
            {
              "timePeriod": "201511010000",
              "activities": 11884,
              "days": 5,
              "jobs": 5
            },
            {
              "timePeriod": "201512010000",
              "activities": 0,
              "days": 0,
              "jobs": 0
            },
            {
              "timePeriod": "201601010000",
              "activities": 0,
              "days": 0,
              "jobs": 0
            }
          ]
        },
        {
          "type": "PowerTrack",
          "used": [
            {
              "timePeriod": "201511010000",
              "activities": 0
            },
            {
              "timePeriod": "201512010000",
              "activities": 27456
            },
            {
              "timePeriod": "201601010000",
              "activities": 0
            }
          ],
          "projected": {
            "timePeriod": "201601010000",
            "activities": 0
          },
          "endpoints": [
            {
              "type": "PowerTrack",
              "label": "devel",
              "used": [
                {
                  "timePeriod": "201511010000",
                  "activities": 0
                },
                {
                  "timePeriod": "201512010000",
                  "activities": 2930
                },
                {
                  "timePeriod": "201601010000",
                  "activities": 0
                }
              ],
              "projected": {
                "timePeriod": "201601010000",
                "activities": 0
              }
            },
            {
              "type": "PowerTrack 2.0",
              "label": "devel-v2",
              "used": [
                {
                  "timePeriod": "201511010000",
                  "activities": 0
                },
                {
                  "timePeriod": "201512010000",
                  "activities": 24542
                },
                {
                  "timePeriod": "201601010000",
                  "activities": 0
                }
              ],
              "projected": {
                "timePeriod": "201601010000",
                "activities": 0
              }
            },
            {
              "type": "PowerTrack 2.0",
              "label": "devel-v2-1",
              "used": [
                {
                  "timePeriod": "201511010000",
                  "activities": 0
                },
                {
                  "timePeriod": "201512010000",
                  "activities": 0
                },
                {
                  "timePeriod": "201601010000",
                  "activities": 0
                }
              ],
              "projected": {
                "timePeriod": "201601010000",
                "activities": 0
              }
            }
          ]
        },
        {
          "type": "Search API",
          "used": [
            {
              "timePeriod": "201511010000",
              "activities": 0,
              "searchRequests30Day": 0
            },
            {
              "timePeriod": "201512010000",
              "activities": 0,
              "searchRequests30Day": 0
            },
            {
              "timePeriod": "201601010000",
              "activities": 0,
              "searchRequests30Day": 0
            }
          ],
          "projected": {
            "timePeriod": "201601010000",
            "activities": 0,
            "searchRequests30Day": 0
          },
          "endpoints": [
            {
              "type": "Search API",
              "label": "devel",
              "used": [
                {
                  "timePeriod": "201511010000",
                  "activities": 0,
                  "searchRequests30Day": 0
                },
                {
                  "timePeriod": "201512010000",
                  "activities": 0,
                  "searchRequests30Day": 0
                },
                {
                  "timePeriod": "201601010000",
                  "activities": 0,
                  "searchRequests30Day": 0
                }
              ],
              "projected": {
                "timePeriod": "201601010000",
                "activities": 0,
                "searchRequests30Day": 0
              }
            }
          ]
        },
        {
          "type": "Search API (30-Day)",
          "used": [
            {
              "timePeriod": "201511010000",
              "activities": 0,
              "searchRequests30Day": 0
            },
            {
              "timePeriod": "201512010000",
              "activities": 0,
              "searchRequests30Day": 0
            },
            {
              "timePeriod": "201601010000",
              "activities": 0,
              "searchRequests30Day": 0
            }
          ],
          "projected": {
            "timePeriod": "201601010000",
            "activities": 0,
            "searchRequests30Day": 0
          },
          "endpoints": [
            {
              "type": "Search API (30-Day)",
              "label": "devel",
              "used": [
                {
                  "timePeriod": "201511010000",
                  "activities": 0,
                  "searchRequests30Day": 0
                },
                {
                  "timePeriod": "201512010000",
                  "activities": 0,
                  "searchRequests30Day": 0
                },
                {
                  "timePeriod": "201601010000",
                  "activities": 0,
                  "searchRequests30Day": 0
                }
              ],
              "projected": {
                "timePeriod": "201601010000",
                "activities": 0,
                "searchRequests30Day": 0
              }
            }
          ]
        },
        {
          "type": "Search API (Full-Archive)",
          "used": [
            {
              "timePeriod": "201511010000",
              "activities": 0,
              "searchRequestsFullArchive": 0
            },
            {
              "timePeriod": "201512010000",
              "activities": 0,
              "searchRequestsFullArchive": 0
            },
            {
              "timePeriod": "201601010000",
              "activities": 0,
              "searchRequestsFullArchive": 0
            }
          ],
          "projected": {
            "timePeriod": "201601010000",
            "activities": 0,
            "searchRequestsFullArchive": 0
          },
          "endpoints": [
            {
              "type": "Search API (Full-Archive)",
              "label": "devel",
              "used": [
                {
                  "timePeriod": "201511010000",
                  "activities": 0,
                  "searchRequestsFullArchive": 0
                },
                {
                  "timePeriod": "201512010000",
                  "activities": 0,
                  "searchRequestsFullArchive": 0
                },
                {
                  "timePeriod": "201601010000",
                  "activities": 0,
                  "searchRequestsFullArchive": 0
                }
              ],
              "projected": {
                "timePeriod": "201601010000",
                "activities": 0,
                "searchRequestsFullArchive": 0
              }
            }
          ]
        }
      ]
    }
  ]
}
```

<div id="api-reference">
  ## APIリファレンス
</div>

<div id="get-usage">
  ### get-usage
</div>

<div id="methods">
  #### **Methods**
</div>

| Method                                                      | Description   |
| :---------------------------------------------------------- | :------------ |
| [GET /metrics/usage/accounts/{ACCOUNT_NAME}.json](#GETData) | 使用状況データを取得します |

Where:

* :account\_name は、console.gnip.com に表示されるアカウントに関連付けられた名前で、大文字と小文字が区別されます

<div id="authentication-and-rate-limit">
  #### **認証とレート制限**
</div>

<div id="authentication">
  ##### **Authentication**
</div>

Usage API へのすべてのリクエストには HTTP Basic 認証が必要です。console.gnip.com へのログインや任意の Gnip ストリームへの接続に使用している、アカウントで有効化されている任意のメールアドレス／パスワードの認証情報を使用してください。

<div id="rate-limit">
  ##### **レート制限**
</div>

Usage API では、1 分あたり 2 件のリクエストというレート制限が適用されます。

<div id="best-practices-limitations">
  #### **ベストプラクティスと制限事項**
</div>

<div id="data-availability">
  ##### **データの可用性**
</div>

利用状況データは、データが処理された最後の完全な時間帯 (UTC) までに消費された、重複排除済みのアクティビティに基づいています。通常、データは分単位まで処理・更新されますが、Gnip がシステムをデプロイしている場合はこの限りではありません。

* Usage API により、2018 年 5 月 1 日以降の利用状況データにアクセスできます。2019 年 7 月 1 日以降は、Usage API により、**直近 13 か月間** の利用状況データにアクセスできます。

* `fromDate` と `toDate` で定義される **3 か月ごとの期間** で、利用状況データにアクセスできます。

<div id="requesting-and-receiving-data">
  #### **データの要求と受信**
</div>

Usage API は、アカウントの API エンドポイントに対して HTTP BASIC-AUTH 認証情報を付与した HTTP GET リクエストを送信することで動作します。

<div id="get-request">
  ##### GET リクエスト:
</div>

ユーザー認証情報とアカウント名を使用して、次のエンドポイントに GET リクエストを送信します。

[https://gnip-api.x.com/metrics/usage/accounts/:account\&#95;name.json](https://gnip-api.x.com/metrics/usage/accounts/:account\&#95;name.json)

**Additional Parameters**

|                         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| :---------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| bucket                  | 任意。利用状況データが提供される時間の単位です。利用状況データは日単位または月単位の粒度で取得できます。  <br />  <br />bucket を指定せずにリクエストした場合、月単位の粒度で返されます。  <br />  <br />指定可能な値: 'month' または 'day'                                                                                                                                                                                                                                                                                                                                                                      |
| fromDate (YYYYMMDDHHMM) | 任意。利用状況データは 2018 年 5 月 1 日以降のみ利用可能です。利用状況データが提供される最も古い UTC タイムスタンプを指定します。タイムスタンプは日単位の粒度で、その日付を含みます (例: 201805010000 には 05/01 の 1 日分が含まれます) 。時刻 (時および分) に '0000' 以外の値が指定されたリクエストは、'0000' に切り捨てられます。  <br />  <br />fromDate または toDate を指定せずに行われたリクエストは、当月分の月単位の利用状況データと、過去 2 か月分の履歴データを返します。  <br />  <br />**注意:** 2019 年 6 月 1 日以降、過去 13 か月分のカレンダー月ベースの利用状況データにアクセスできます。たとえば、10 月 10 日の場合、前年の 9 月 1 日までさかのぼって利用状況データにアクセスできます。  <br />**例:** 201810010000 を指定すると、2018 年 10 月 1 日以降のデータが返され、10 月 1 日分も含まれます。          |
| toDate (YYYYMMDDHHMM)   | 任意。利用状況データが提供される最新の UTC タイムスタンプを指定します。タイムスタンプは日単位の粒度で、その日付は含まれません (例: 201703020000 には 03/02 の 1 日分のデータは含まれません) 。toDate に当日または将来の日付が指定された場合、利用状況データは直近の完全な 1 日分 (UTC) まで返されます。時刻 (時および分) に '0000' 以外の値が指定されたリクエストは、'0000' に切り捨てられます。  <br />  <br />toDate を指定しないリクエストでは、次の bucket (bucket=day の場合は翌日、bucket=month の場合は翌月) がデフォルトになります。fromDate と toDate の両方を指定せずに行われたリクエストでは、bucket=month がデフォルトとなり、当月分と直近 2 か月分のデータが返されます。  <br />  <br />**例:** 201703050000 を指定すると、2017 年 3 月 5 日までのデータが返されますが、3 月 5 日分のデータは含まれません。 |

**Example GET Request**

次のリクエストは、2017 年 3 月 1 日から 2017 年 3 月 5 日までの月単位の粒度でデータを返しますが、2017 年 3 月 5 日分のデータは含まれません。

curl -u "[https://gnip-api.x.com/metrics/usage/accounts/:account\&#95;name.json?bucket=month\&amp;fromdate=201403010000\&amp;toDate=201403150000](https://gnip-api.x.com/metrics/usage/accounts/:account\&#95;name.json?bucket=month\&amp;fromdate=201403010000\&amp;toDate=201403150000)"

<div id="data-format">
  #### **Data Format**
</div>

以下のテーブルでは、Usage API から返される利用状況データのルートレベルのデータ構造について説明します。複数レベルのサブフィールドを持つフィールドについては、リンクをクリックするとサブフィールドの詳細を表示できます。

Usage API のペイロード全体のサンプルを確認したい場合は、[このページ](/ja/x-api/usage/introduction)をご覧ください。

|                |                                                 |
| :------------- | :---------------------------------------------- |
| **account**    | 利用状況データがリクエストされたアカウントを表すオブジェクト。                 |
| **bucket**     | 利用状況データが提供される時間単位。'day' または 'month' のいずれか。      |
| **fromDate**   | 取得したい利用状況データの、最も早い UTC タイムスタンプ (含む) 。           |
| **toDate**     | 取得したい利用状況データの、最も遅い UTC タイムスタンプ (含まない) 。         |
| **publishers** | Used、projected、products という 3 つの主要なオブジェクトを含みます。 |