{title}
{description}
{description}
Get immediate access to the X API and unlock the potential of X data
Businesses, researchers, and developers all over the world have used the X Developer Platform to creatively innovate, gain valuable insights, and shape the future. Explore how they did it and get inspired to use the APIs in your own way.
Browse all success stories{description}
{description}
{description}
**Example request (Authorization header has been wrapped):**
```
POST /oauth/request_token HTTP/1.1
User-Agent: themattharris' HTTP Client
Host: api.x.com
Accept: */*
Authorization:
OAuth oauth_callback="http%3A%2F%2Flocalhost%2Fsign-in-with-twitter%2F",
oauth_consumer_key="cChZNFj6T5R0TigYB9yd1w",
oauth_nonce="ea9ec8429b68d6b77cd5600adbbb0456",
oauth_signature="F1Li3tvehgcraF8DMJ7OyxO4w9Y%3D",
oauth_signature_method="HMAC-SHA1",
oauth_timestamp="1318467427",
oauth_version="1.0"
```
Your app should examine the HTTP status of the response. Any value other than 200 indicates a failure. The body of the response will contain the oauth\_token, oauth\_token\_secret, and oauth\_callback\_confirmed parameters. Your app should verify that oauth\_callback\_confirmed is true and store the other two values for the next steps.
**Example response (response body has been wrapped):**
```
HTTP/1.1 200 OK
Date: Thu, 13 Oct 2011 00:57:06 GMT
Status: 200 OK
Content-Type: text/html; charset=utf-8
Content-Length: 146
Pragma: no-cache
Expires: Tue, 31 Mar 1981 05:00:00 GMT
Cache-Control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0
Vary: Accept-Encoding
Server: tfe
oauth_token=NPcudxy0yU5T3tBzho7iCotZ3cnetKwcTIRlX0iwRl0&
oauth_token_secret=veNRnAWe6inFuo8o2u8SLLZLjolYDmDP7SzL0YfYI&
oauth_callback_confirmed=true
```
Sign in with X (link style):
To demonstrate the flows, pretend the website pictured above (“The greatest website ever created”) has implemented this API, as shown by the Sign in with X button on the landing page.
When the user clicks the Sign in button, the page they see depends on whether they are signed in and whether they have previously allowed the application to access their account.
When the user is signed in to x.com but has not granted access, a list of requested permissions, along with Sign In and Cancel buttons are shown.
When the user is not signed in to x.com input fields for a username and password will be shown. Note that even if the user has already granted access to the application, the list of permissions will still be shown.
After the user inputs valid credentials (if needed) and clicks “Sign In”, X will redirect the user to the website which started the sign in flow.
In the case where the user is already signed in to x.com and has granted access to the website, this redirect happens immediately.
When you redirect to X with the request token, the user will be prompted to authorize your application.
Upon authorizing your application, the user will be redirected to the callback URL provided when you generated the request token. You will use this to obtain the permanent access token for this user and store it locally.
# Percent encoding parameters
Source: https://docs.x.com/resources/fundamentals/authentication/oauth-1-0a/percent-encoding-parameters
export const Button = ({href, children}) => {
return ;
};
### Percent encoding parameters
Parts of the X API, particularly those dealing with OAuth signatures, require strings to be encoded according to [RFC 3986, Section 2.1](http://tools.ietf.org/html/rfc3986#section-2.1). Since many implementations of URL encoding algorithms are not fully compatible with RFC 3986, bad encodings are a cause of many OAuth signature errors. For this reason, the exact signing algorithm to use is covered on this page.
This page covers the URL encoding process described in [RFC 3986, Section 2.1](http://tools.ietf.org/html/rfc3986#section-2.1). We encourage you to reference that specification in case of any ambiguity or conflict with this document.
#### Encoding a string
The following algorithm assumes you are encoding a string SRC by copying its values byte-by-byte to a string DST.
**Step 1: While SRC contains unread bytes, read the next byte (8 bits) from SRC.** Typically, this is considered a character, but in the case of encodings where a character may be more than one byte (such as UTF-8), just read the first byte.
**Step 2: Check whether the read byte matches any of the following ASCII equivalents.** The following table has been broken down into rows for legibility, but you only need to determine whether the read byte exists in the table at all, not the specific row.
| Name | ASCII characters | Equivalent byte values |
| :------------------ | :------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------- |
| Digits | ‘0’, ‘1’, ‘2’, ‘3’, ‘4’, ‘5’, ‘6’, ‘7’, ‘8’, ‘9’ | 0x30, 0x31, 0x32, 0x33, 0x34, 0x35, 0x36, 0x37, 0x38, 0x39 |
| Uppercase letters | ‘A’, ‘B’, ‘C’, ‘D’, ‘E’, ‘F’, ‘G’, ‘H’, ‘I’, ‘J’, ‘K’, ‘L’, ‘M’, ‘N’, ‘O’, ‘P’, ‘Q’, ‘R’, ‘S’, ‘T’, ‘U’, ‘V’, ‘W’, ‘X’, ‘Y’, ‘Z’ | 0x41, 0x42, 0x43, 0x44, 0x45,0x46, 0x47, 0x48, 0x49, 0x4A, 0x4B,0x4C, 0x4D, 0x4E, 0x4F, 0x50, 0x51,0x52, 0x53, 0x54, 0x55, 0x56, 0x57,0x58, 0x59, 0x5A |
| Lowercase letters | ‘a’, ‘b’, ‘c’, ‘d’, ‘e’, ‘f’, ‘g’, ‘h’, ‘i’, ‘j’, ‘k’, ‘l’, ‘m’, ‘n’, ‘o’, ‘p’, ‘q’, ‘r’, ‘s’, ‘t’, ‘u’, ‘v’, ‘w’, ‘x’, ‘y’, ‘z’ | 0x61, 0x62, 0x63, 0x64, 0x65,0x66, 0x67, 0x68, 0x69, 0x6A, 0x6B,0x6C, 0x6D, 0x6E, 0x6F, 0x70, 0x71,0x72, 0x73, 0x74, 0x75, 0x76, 0x77,0x78, 0x79, 0x7A |
| Reserved characters | ‘-‘, ‘.’, ‘\_’, ‘\~’ | 0x2D, 0x2E, 0x5F, 0x7E |
**Step 2b: If the byte is not listed in the above table, continue.** Any other value must be encoded. **Step 2a: If the byte is listed in the above table, copy it into DST and go back to Step 1.** Characters listed in the above table do not need to be escaped, so you will just copy the byte directly.
**Step 3: Write the character ‘%’ to DST.** The percent character ‘%’ (or 0x25 in hex and 00100101 in binary) indicates that the next two bytes will represent an encoded byte.
**Step 4: Write two characters representing the uppercase ASCII-encoded hex value of the current byte to DST.** This is a bit confusing, so here is an example. Pretend the current byte is 0xE6 (11100110 in binary). This corresponds with the UTF-8 encoded value of ‘æ’. To encode this value, write the character ‘E’ (0x45, from the table above) and then the character ‘6’ (0x36) to DST. The last three characters are written should have been “%E6”. Note that if you write a letter such as A,B,C,D,E or F, you must use the uppercase character.
**Step 5: Return to Step 1.** Keep going until the entirety of SRC is copied to DST.
#### Examples
The following examples may be helpful to compare with the output of your own code. You should consider any differences an error. Spaces encoded as “+” characters are an example of incorrect encoding.
| Original string | Encoded string |
| :----------------- | :-------------------------- |
| Ladies + Gentlemen | Ladies%20%2B%20Gentlemen |
| An encoded string! | An%20encoded%20string%21 |
| Dogs, Cats & Mice | Dogs%2C%20Cats%20%26%20Mice |
| ☃ | %E2%98%83 |
# PIN-based authorization
Source: https://docs.x.com/resources/fundamentals/authentication/oauth-1-0a/pin-based-oauth
export const Button = ({href, children}) => {
return ;
};
### PIN-based authorization
The PIN-based OAuth flow is a version of the [3-legged OAuth](/resources/fundamentals/authentication/oauth-1-0a/obtaining-user-access-tokens) process and is intended for applications that cannot access or embed a web browser to redirect the user after authorization. Examples of such applications would be command-line applications, embedded systems, game consoles, and certain types of mobile apps.
PIN-based OAuth flow is initiated by an app in the `request_token` with the `oauth_callback` set to `oob`. The term `oob` means out-of-band OAuth. The user still visits X to login or authorize the app, but they will not be automatically redirected to the application upon approving access. Instead, they will see a numerical PIN code, with instructions to return to the application and enter this value.
#### About application-only auth
**Tokens are passwords**
Keep in mind that the consumer key & secret and the App only Access Token (Bearer Token) itself grant access to make requests on behalf of an application. These values should be considered as sensitive as passwords, and must not be shared or distributed to untrusted parties.
**SSL required**
All requests (both to obtain and use the tokens) *must* use HTTPS endpoints. Follow the best practices detailed in [Connecting to X API using TLS](/resources/fundamentals/authentication/guides/tls) — peers should **always** be verified.
**No user-context**
When issuing requests using application-only auth, there is no concept of a "current user". Therefore, endpoints such as [POST statuses/update](/x-api/posts/creation-of-a-post) will not function with application-only auth. See [using OAuth](/resources/fundamentals/authentication/oauth-1-0a/obtaining-user-access-tokens) for more information for issuing requests on behalf of a user.
**Rate limiting**
Applications have two kinds of rate limiting pools.
Requests made on behalf of users with access tokens, also known as user-context, depletes from a different rate limiting context than that used in application-only authentication. So, in other words, requests made on behalf of users will not deplete from the rate limits available through app-only auth, and requests made through app-only auth will not deplete from the rate limits used in user-based auth.
Read more about [API Rate Limiting](/x-api/fundamentals/rate-limits) and [review the limits](https://developer.x.com/en/portal/products).
#### Issuing application-only requests
**Step 1: Encode consumer key and secret**
The steps to encode an application’s consumer key and secret into a set of credentials to obtain a Bearer Token are:
1. URL encode the consumer key and consumer secret according to [RFC 1738](http://www.ietf.org/rfc/rfc1738.txt). Note that at the time of writing, this will not actually change the consumer key and secret, but this step should still be performed in case the format of those values changes in the future.
2. Concatenate the encoded consumer key, a colon character ":", and the encoded consumer secret into a single string.
3. [Base64 encode](http://en.wikipedia.org/wiki/Base64) the string from the previous step.
Below are example values showing the result of this algorithm. Note that the consumer secret used in this page is for test purposes and will not work for real requests.
| | |
| :------------------------------------------------------------ | :------------------------------------------------------------------------------------------ |
| Consumer key | xvz1evFS4wEEPTGEFPHBog |
| Consumer secret | L8qq9PZyRg6ieKGEKhZolGC0vJWLw8iEJ88DRdyOg |
| RFC 1738 encoded consumer| Endpoint | Pro Limit | Basic Limit | Free Limit |
|---|---|---|---|
| Tweets | |||
| DELETE /2/tweets/:id | 50 requests / 15 mins PER USER |
5 requests / 15 mins PER USER |
17 requests / 24 hours PER USER 17 requests / 24 hours PER APP |
| DELETE /2/users/:id/likes/:tweet\_id | 50 requests / 15 mins PER USER |
100 requests / 24 hours PER USER |
1 requests / 15 mins PER USER |
| DELETE /2/users/:id/retweets/:tweet\_id | 50 requests / 15 mins PER USER |
5 requests / 15 mins PER USER |
1 requests / 15 mins PER USER |
| GET /2/tweets | 900 requests / 15 mins PER USER 450 requests / 15 mins PER APP |
15 requests / 15 mins PER USER 15 requests / 15 mins PER APP |
1 requests / 15 mins PER USER 1 requests / 15 mins PER APP |
| GET /2/tweets/:id | 900 requests / 15 mins PER USER 450 requests / 15 mins PER APP |
15 requests / 15 mins PER USER 15 requests / 15 mins PER APP |
1 requests / 15 mins PER USER 1 requests / 15 mins PER APP |
| GET /2/tweets/:id/liking\_users | 75 requests / 15 mins PER USER 75 requests / 15 mins PER APP |
5 requests / 15 mins PER USER 25 requests / 15 mins PER APP |
1 requests / 15 mins PER USER 1 requests / 15 mins PER APP |
| GET /2/tweets/:id/quote\_tweets | 75 requests / 15 mins PER USER 75 requests / 15 mins PER APP |
5 requests / 15 mins PER USER 5 requests / 15 mins PER APP |
1 requests / 15 mins PER USER 1 requests / 15 mins PER APP |
| GET /2/tweets/:id/retweeted\_by | 75 requests / 15 mins PER USER 75 requests / 15 mins PER APP |
5 requests / 15 mins PER USER 5 requests / 15 mins PER APP |
1 requests / 15 mins PER USER 1 requests / 15 mins PER APP |
| GET /2/tweets/counts/all | 300 requests / 15 mins PER APP |
|
|
| GET /2/tweets/counts/recent | 300 requests / 15 mins PER APP |
5 requests / 15 mins PER APP |
1 requests / 15 mins PER APP |
| GET /2/tweets/search/all | 1 requests / second PER USER 1 requests / second PER APP |
|
|
| GET /2/tweets/search/recent | 300 requests / 15 mins PER USER 450 requests / 15 mins PER APP |
60 requests / 15 mins PER USER 60 requests / 15 mins PER APP |
1 requests / 15 mins PER USER 1 requests / 15 mins PER APP |
| GET /2/tweets/search/stream | 50 requests / 15 mins PER APP |
|
|
| GET /2/tweets/search/stream/rules | 450 requests / 15 mins PER APP |
|
|
| GET /2/users/:id/liked\_tweets | 75 requests / 15 mins PER USER 75 requests / 15 mins PER APP |
5 requests / 15 mins PER USER 5 requests / 15 mins PER APP |
1 requests / 15 mins PER USER 1 requests / 15 mins PER APP |
| GET /2/users/:id/mentions | 300 requests / 15 mins PER USER 450 requests / 15 mins PER APP |
10 requests / 15 mins PER USER 15 requests / 15 mins PER APP |
1 requests / 15 mins PER USER 1 requests / 15 mins PER APP |
| GET /2/users/:id/timelines/reverse\_chronological | 180 requests / 15 mins PER USER |
5 requests / 15 mins PER USER |
1 requests / 15 mins PER USER |
| GET /2/users/:id/tweets | 900 requests / 15 mins PER USER 1500 requests / 15 mins PER APP |
5 requests / 15 mins PER USER 10 requests / 15 mins PER APP |
1 requests / 15 mins PER USER 1 requests / 15 mins PER APP |
| GET /2/users/reposts\_of\_me | 75 requests / 15 mins PER USER |
75 requests / 15 mins PER USER |
1 requests / 15 mins PER USER |
| POST /2/tweets | 100 requests / 15 mins PER USER 10000 requests / 24 hours PER APP |
100 requests / 24 hours PER USER 1667 requests / 24 hours PER APP |
17 requests / 24 hours PER USER 17 requests / 24 hours PER APP |
| POST /2/tweets/search/stream/rules | 100 requests / 15 mins PER APP |
|
|
| POST /2/users/:id/likes | 1000 requests / 24 hours PER USER |
200 requests / 24 hours PER USER |
1 requests / 15 mins PER USER |
| POST /2/users/:id/retweets | 50 requests / 15 mins PER USER |
5 requests / 15 mins PER USER |
1 requests / 15 mins PER USER |
| PUT /2/tweets/:tweet\_id/hidden | 50 requests / 15 mins PER USER |
5 requests / 15 mins PER USER |
1 requests / 15 mins PER USER |
| Users | |||
| DELETE /2/users/:source\_user\_id/following/:target\_user\_id | 50 requests / 15 mins PER USER |
5 requests / 15 mins PER USER |
1 requests / 15 mins PER USER |
| DELETE /2/users/:source\_user\_id/muting/:target\_user\_id | 50 requests / 15 mins PER USER |
5 requests / 15 mins PER USER |
1 requests / 15 mins PER USER |
| GET /2/users | 900 requests / 15 mins PER USER 300 requests / 15 mins PER APP |
100 requests / 24 hours PER USER 500 requests / 24 hours PER APP |
1 requests / 24 hours PER USER 1 requests / 24 hours PER APP |
| GET /2/users/:id | 900 requests / 15 mins PER USER 300 requests / 15 mins PER APP |
100 requests / 24 hours PER USER 500 requests / 24 hours PER APP |
1 requests / 24 hours PER USER 1 requests / 24 hours PER APP |
| GET /2/users/:id/blocking | 15 requests / 15 mins PER USER |
5 requests / 15 mins PER USER |
1 requests / 15 mins PER USER |
| GET /2/users/:id/muting | 15 requests / 15 mins PER USER |
100 requests / 24 hours PER USER |
1 requests / 24 hours PER USER |
| GET /2/users/by | 900 requests / 15 mins PER USER 300 requests / 15 mins PER APP |
100 requests / 24 hours PER USER 500 requests / 24 hours PER APP |
1 requests / 24 hours PER USER 1 requests / 24 hours PER APP |
| GET /2/users/by/username/:username | 900 requests / 15 mins PER USER 300 requests / 15 mins PER APP |
100 requests / 24 hours PER USER 500 requests / 24 hours PER APP |
3 requests / 15 mins PER USER 3 requests / 15 mins PER APP |
| GET /2/users/me | 75 requests / 15 mins PER USER |
250 requests / 24 hours PER USER |
25 requests / 24 hours PER USER |
| GET /2/users/search | 900 requests / 15 mins PER USER 300 requests / 15 mins PER APP |
|
|
| POST /2/users/:id/following | 50 requests / 15 mins PER USER |
5 requests / 15 mins PER USER |
1 requests / 15 mins PER USER |
| POST /2/users/:id/muting | 50 requests / 15 mins PER USER |
5 requests / 15 mins PER USER |
1 requests / 15 mins PER USER |
| Spaces | |||
| GET /2/spaces | 300 requests / 15 mins PER USER 300 requests / 15 mins PER APP |
5 requests / 15 mins PER USER 25 requests / 15 mins PER APP |
1 requests / 15 mins PER USER 1 requests / 15 mins PER APP |
| GET /2/spaces/:id | 300 requests / 15 mins PER USER 300 requests / 15 mins PER APP |
5 requests / 15 mins PER USER 25 requests / 15 mins PER APP |
1 requests / 15 mins PER USER 1 requests / 15 mins PER APP |
| GET /2/spaces/:id/buyers | 300 requests / 15 mins PER USER 300 requests / 15 mins PER APP |
5 requests / 15 mins PER USER 25 requests / 15 mins PER APP |
1 requests / 15 mins PER USER 1 requests / 15 mins PER APP |
| GET /2/spaces/:id/tweets | 300 requests / 15 mins PER USER 300 requests / 15 mins PER APP |
5 requests / 15 mins PER USER 25 requests / 15 mins PER APP |
1 requests / 15 mins PER USER 1 requests / 15 mins PER APP |
| GET /2/spaces/by/creator\_ids | 300 requests / 15 mins PER USER 1 requests / second PER APP |
5 requests / 15 mins PER USER 25 requests / second PER APP |
1 requests / second PER USER 1 requests / 15 mins PER APP |
| GET /2/spaces/search | 300 requests / 15 mins PER USER 300 requests / 15 mins PER APP |
5 requests / 15 mins PER USER 25 requests / 15 mins PER APP |
1 requests / 15 mins PER USER 1 requests / 15 mins PER APP |
| Direct Messages | |||
| DELETE /2/dm\_events/:id | 1500 requests / 24 hours PER USER 4000 requests / 24 hours PER APP |
200 requests / 15 mins PER USER 2500 requests / 24 hours PER APP |
|
| GET /2/dm\_conversations/:dm\_conversation\_id/dm\_events | 15 requests / 15 mins PER USER |
1 requests / 24 hours PER USER |
|
| GET /2/dm\_conversations/with/:participant\_id/dm\_events | 15 requests / 15 mins PER USER |
1 requests / 24 hours PER USER |
|
| GET /2/dm\_events | 15 requests / 15 mins PER USER |
1 requests / 24 hours PER USER |
|
| GET /2/dm\_events/:id | 15 requests / 15 mins PER USER |
5 requests / 24 hours PER USER |
|
| POST /2/dm\_conversations | 15 requests / 15 mins PER USER 1440 requests / 24 hours PER APP |
1 requests / 24 hours PER USER 1 requests / 24 hours PER APP |
|
| POST /2/dm\_conversations/:dm\_conversation\_id/messages | 15 requests / 15 mins PER USER 1440 requests / 24 hours PER APP |
1 requests / 24 hours PER USER 1 requests / 24 hours PER APP |
|
| POST /2/dm\_conversations/with/:participant\_id/messages | 1440 requests / 24 hours PER USER 1440 requests / 24 hours PER APP |
1 requests / 24 hours PER USER 1 requests / 24 hours PER APP |
|
| Lists | |||
| DELETE /2/lists/:id | 300 requests / 15 mins PER USER |
5 requests / 15 mins PER USER |
1 requests / 15 mins PER USER |
| DELETE /2/lists/:id/members/:user\_id | 300 requests / 15 mins PER USER |
5 requests / 15 mins PER USER |
1 requests / 15 mins PER USER |
| DELETE /2/users/:id/followed\_lists/:list\_id | 50 requests / 15 mins PER USER |
5 requests / 15 mins PER USER |
1 requests / 15 mins PER USER |
| DELETE /2/users/:id/pinned\_lists/:list\_id | 50 requests / 15 mins PER USER |
5 requests / 15 mins PER USER |
1 requests / 15 mins PER USER |
| GET /2/lists/:id | 75 requests / 15 mins PER USER 75 requests / 15 mins PER APP |
5 requests / 15 mins PER USER 5 requests / 15 mins PER APP |
1 requests / 15 mins PER USER 1 requests / 15 mins PER APP |
| GET /2/lists/:id/members | 900 requests / 15 mins PER USER 900 requests / 15 mins PER APP |
5 requests / 15 mins PER USER 25 requests / 15 mins PER APP |
1 requests / 15 mins PER USER 1 requests / 15 mins PER APP |
| GET /2/lists/:id/tweets | 900 requests / 15 mins PER USER 900 requests / 15 mins PER APP |
5 requests / 15 mins PER USER 25 requests / 15 mins PER APP |
|
| GET /2/users/:id/list\_memberships | 75 requests / 15 mins PER USER 75 requests / 15 mins PER APP |
5 requests / 15 mins PER USER 25 requests / 15 mins PER APP |
1 requests / 15 mins PER USER 1 requests / 15 mins PER APP |
| GET /2/users/:id/owned\_lists | 15 requests / 15 mins PER USER 15 requests / 15 mins PER APP |
100 requests / 24 hours PER USER 500 requests / 24 hours PER APP |
1 requests / 24 hours PER USER 1 requests / 24 hours PER APP |
| GET /2/users/:id/pinned\_lists | 15 requests / 15 mins PER USER 15 requests / 15 mins PER APP |
100 requests / 24 hours PER USER 500 requests / 24 hours PER APP |
1 requests / 24 hours PER USER 1 requests / 24 hours PER APP |
| POST /2/lists | 300 requests / 15 mins PER USER |
100 requests / 24 hours PER USER |
1 requests / 24 hours PER USER |
| POST /2/lists/:id/members | 300 requests / 15 mins PER USER |
5 requests / 15 mins PER USER |
1 requests / 15 mins PER USER |
| POST /2/users/:id/followed\_lists | 50 requests / 15 mins PER USER |
5 requests / 15 mins PER USER |
1 requests / 15 mins PER USER |
| POST /2/users/:id/pinned\_lists | 50 requests / 15 mins PER USER |
5 requests / 15 mins PER USER |
1 requests / 15 mins PER USER |
| PUT /2/lists/:id | 300 requests / 15 mins PER USER |
5 requests / 15 mins PER USER |
1 requests / 15 mins PER USER |
| Bookmarks | |||
| DELETE /2/users/:id/bookmarks/:tweet\_id | 50 requests / 15 mins PER USER |
5 requests / 15 mins PER USER |
1 requests / 15 mins PER USER |
| GET /2/users/:id/bookmarks | 180 requests / 15 mins PER USER |
10 requests / 15 mins PER USER |
1 requests / 15 mins PER USER |
| GET /2/users/:id/bookmarks/folders | 50 requests / 15 mins PER USER 50 requests / 15 mins PER APP |
5 requests / 15 mins PER USER 5 requests / 15 mins PER APP |
1 requests / 15 mins PER USER 1 requests / 15 mins PER APP |
| GET /2/users/:id/bookmarks/folders/:folder\_id | 50 requests / 15 mins PER USER 50 requests / 15 mins PER APP |
5 requests / 15 mins PER USER 5 requests / 15 mins PER APP |
1 requests / 15 mins PER USER 1 requests / 15 mins PER APP |
| POST /2/users/:id/bookmarks | 50 requests / 15 mins PER USER |
5 requests / 15 mins PER USER |
1 requests / 15 mins PER USER |
| Compliance | |||
| GET /2/compliance/jobs | 150 requests / 15 mins PER APP |
5 requests / 15 mins PER APP |
1 requests / 15 mins PER APP |
| GET /2/compliance/jobs/:job\_id | 150 requests / 15 mins PER APP |
5 requests / 15 mins PER APP |
1 requests / 15 mins PER APP |
| POST /2/compliance/jobs | 150 requests / 15 mins PER APP |
15 requests / 15 mins PER APP |
1 requests / 15 mins PER APP |
| Usage | |||
| GET /2/usage/tweets | 50 requests / 15 mins PER APP |
50 requests / 15 mins PER APP |
1 requests / 15 mins PER APP |
| Trends | |||
| GET /2/trends/by/woeid/:id | 75 requests / 15 mins PER APP |
15 requests / 15 mins PER APP |
|
| GET /2/users/personalized\_trends | 10 requests / 15 mins PER USER 200 requests / 15 mins PER APP |
1 requests / 15 mins PER USER 20 requests / 15 mins PER APP |
1 requests / 15 mins PER USER 1 requests / 24 hours PER APP |
| Communities | |||
| GET /2/communities/:id | 300 requests / 15 mins PER USER 300 requests / 15 mins PER APP |
1 requests / 15 mins PER USER 25 requests / 15 mins PER APP |
1 requests / 15 mins PER USER 1 requests / 15 mins PER APP |
| GET /2/communities/search | 300 requests / 15 mins PER USER 300 requests / 15 mins PER APP |
1 requests / 15 mins PER USER 25 requests / 15 mins PER APP |
1 requests / 15 mins PER USER 1 requests / 15 mins PER APP |
Along with X API v2, we launched a new versioning strategy that enables developers to better understand when to expect changes to X's public APIs, and when they will need to migrate to new versions.
Developers will be notified of deprecations, retirements, changes, and additions to the X API via our communication channels so they can appropriately plan to accommodate these changes in their development roadmap. All changes to the API will be noted in the changelog.
The X API currently has three different versions. We strongly encourage users to utilize X API v2 when planning their integration unless we have not released functionality to v2 that is required by your use case.
To learn more about each version, please visit the following pages:
Versioning for the X API will be represented by version numbers declared in the route path for our endpoints:
`https://api.x.com/2/tweets`
We aim to release major versions of the X API as necessary but no more frequently than every 12 months. A major version will be released when breaking changes are introduced in the API. We will publish migration guides when launching a new major version to help developers migrate over to the new version.
A breaking change requires developers to change their code to maintain existing functionality in their app. Non-breaking changes will be additive and rolled out to the most recent version when ready, requiring no work on a developer’s end unless you would like to take advantage of the new functionality.
If a breaking change must be rolled out mid-cycle (for security or privacy reasons), this change will be made to the most recent version.
### Breaking changesThese changes require developers to change their code to maintain existing functionality of their application.
First of all, here is our definition of what deprecation and retirement mean to the X API:
In most cases, as soon as a new version is released, the previous version will be marked as deprecated. Versions will remain in a deprecated state for a period of time, after which they will be retired.
Please stay informed to learn more about future deprecations and retirements.
# About the X API Source: https://docs.x.com/x-api/getting-started/about-x-api The X API can be used to programmatically retrieve and analyze X data, as well as build for the conversation on X. Over the years, the X API has grown by adding additional levels of access for developers to be able to scale their access to enhance and research the public conversation. Recently, we released the X API v2. The X API v2 includes a modern foundation, new and advanced features, and quick onboarding to [Basic access](https://developer.x.com/en/portal/products/basic). The following three tabs explain the different versions and access levels of the X API, what’s new with v2, and which X resources you can retrieve, create, destroy, and adjust using the API.
When you redirect to X with the request token, the user will be prompted to authorize your application
Upon authorizing your application, the user will be redirected to the callback URL provided when you generated the request token. You will use this to obtain the permanent access token for this user and store it locally!
# Currency
Source: https://docs.x.com/x-ads-api/fundamentals/currency
The type of a currency is identified using [ISO-4217](http://en.wikipedia.org/wiki/ISO_4217). This is a three-letter string like `USD` or `EUR`. The value of a currency is represented in micros. For USD, \$5.50 is encoded as 5.50\*1e6, or 5,500,000. To represent a “whole value”, you need to multiply the local micro by 1e6 (1\_000\_000) for all currencies.
The Ads API recognizes official currencies of all countries where the X SMB Ads product is available. For a complete list of these countries, please click [here](https://business.x.com/en/help/overview/about-eligibility-for-twitter-ads.html).
Most currencies have a “precision” of two (like USD: \$1.23).
* `AED`, `VEF`, `PKR`, `IDR`, `HKD`, `QAR`, `PHP`, `NZD`, `INR`, `EUR`, `ARS`, `THB`, `MXN`, `EGP`, `DZD`, `SAR`, `LBP`, `COP`, `TRY`, `SGD`, `MAD`, `AUD`, `USD`, `MYR`, `CAD`, `BRL`, `GBP`.
The following currencies don’t use a decimal:
* `VND`, `KRW`, `CLP`, `JPY`
And these use three decimal places:
* `KWD`, `IQD`, `BHD`, `TND`
The usage of currency is accomplished through [funding instruments](/x-ads-api/introduction).
# Error codes and responses
Source: https://docs.x.com/x-ads-api/fundamentals/error-codes-and-responses
## Typical Response Structure
Successful responses are indicated with a 200-series HTTP code and a JSON-based payload containing the object(s) requested, created, modified, or deleted along with an expression of the server’s interpretation of your request.
If you had issued a successful request you would receive as part of your response a `request` node echoing back your request.
*Example:* [GET accounts/abcdefg/campaigns?with\_deleted=true](/x-ads-api/campaign-management#campaigns)
```json
{
/* the data of your response... */,
"request": {
"params": {
"account_id": "abcdefg",
"with_deleted": "true"
}
}
}
```
The `data` field in JSON responses will contain the specific objects associated with the leveraged resource. The format of the `data` node will be a JSON array when the response may contain one or more results. It will be returned as JSON hash when only one result is possible in response. In some rare cases, you may see a response that would typically include a collection with a hashmap instead. In this case, assume the single hashmap is an object of the same type as specified in the `type` field.
## Error Response Structure
Error responses are served with a non-200-series HTTP code. Usually a JSON response will be attached, but some errors will respond with different kinds of body. In these circumstances where a response structure cannot be parsed, consider the HTTP code’s core meaning to take precedence. For instance, you may occasionally see a HTTP 404 along with a HTML response. In this case, it’s safe to assume that the content cannot be found (HTTP 404 means “Not Found”).
Typical error responses follow a similar structure to successful responses. The nature of the error will be communicated in an `errors` node of the response. The `errors/code` node will indicate a CAPS\_CASE constant error code you can programmatically consume to make resolution decisions from. The `errors/message` node will indicate a (usually) human-readable description of the error in English. Additional fields may be attached to indicate finer-grained detail about the error.
```json
{
"errors": [
{
"parameter": "start_time",
"details": "invalid date",
"code": "INVALID_PARAMETER",
"value": "",
"message": "Expected time, got \"\" for start_time"
}
],
"request": {
"params": {
"account_id": "hkk5"
}
}
}
```
In the above example, a request to an analytics endpoint was made with an invalid value for the `start_time` parameter. The `errors/code` for requests with invalid parameters is `INVALID_PARAMETER`.
| HTTP Code | Error Code |
| :-------- | :---------------------------------------------------------- |
| 403 | `ACCOUNT_LOCKED_OUT` |
| 404 | `ACCOUNT_MEDIA_NOT_FOUND` |
| 403 | `ACCOUNT_NOT_FOUND` |
| 403 | `ACTION_NOT_ALLOWED` |
| 404 | `APP_EVENT_PROVIDER_CONFIGURATION_NOT_FOUND` |
| 404 | `APP_EVENT_TAG_NOT_FOUND` |
| 404 | `BEHAVIOR_OR_BEHAVIOR_EXPANDED_NOT_FOUND` |
| 404 | `CAMPAIGN_NOT_FOUND` |
| 408 | `CANCELLED_REQUEST` |
| 404 | `CARD_NOT_FOUND` |
| 403 | `CURRENT_USER_SUSPENDED` |
| 400 | `DUPLICATE_TWEET` |
| 400 | `EXCLUSIVE_PARAMETERS` |
| 400 | `FEATURE_NOT_AVAILABLE` |
| 403 | `FUNDING_INSTRUMENT_ACCESS_NOT_ALLOWED` |
| 403 | `FUNDING_INSTRUMENT_EXCEEDS_AVAILABLE_CREDIT_LIMIT` |
| 404 | `FUNDING_INSTRUMENT_NOT_FOUND` |
| 403 | `GENERIC_TWEET_ERROR` |
| 400 | `ILLEGAL_CHARACTERS` |
| 400 | `INCLUSIVE_PARAMETERS` |
| 500 | `INTERNAL_ERROR` |
| 404 | `INVALID_APP_ID` |
| 404 | `INVALID_APP_STORE` |
| 400 | `INVALID_DENOMINATION` |
| 400 | `INVALID_FUNDING_INSTRUMENT` |
| 404 | `INVALID_IAB_CATEGORY` |
| 404 | `INVALID_ID_ILLEGAL_CHARACTERS` |
| 400 | `INVALID_IMAGE` |
| 400 | `INVALID_MEDIA` |
| 400 | `INVALID_MEDIA_ID` |
| 400 | `INVALID_PARAMETER` |
| 400 | `INVALID_PLACEMENT_TYPE` |
| 400 | `INVALID_TAILORED_AUDIENCE_TYPE` |
| 400 | `INVALID_TARGETING_TYPE` |
| 400 | `INVALID_TIME_WINDOW` |
| 400 | `INVALID_TV_SHOW_LOCATIONS` |
| 400 | `INVALID_TWEET` |
| 400 | `INVALID_USER` |
| 400 | `INVALID_USER_ID` |
| 423 | `LOCK_ACQUISITION_TIMEOUT` |
| 404 | `LINE_ITEM_APP_NOT_FOUND` |
| 404 | `LINE_ITEM_NOT_FOUND` |
| 404 | `MACT_APP_NOT_FOUND` |
| 403 | `MALWARE_STATUS` |
| 404 | `MEDIA_CREATIVE_NOT_FOUND` |
| 404 | `MEDIA_NOT_FOUND` |
| 405 | `METHOD_NOT_ALLOWED` |
| 400 | `MISSING_PARAMETER` |
| 404 | `NO_PROVIDER_AVAILABLE_FOR_THIS_CLIENT_APPLICATION` |
| 404 | `NOT_FOUND` |
| 404 | `PROMOTABLE_USER_NOT_FOUND` |
| 404 | `PROMOTED_ACCOUNT_NOT_FOUND` |
| 404 | `PROMOTED_TWEET_NOT_FOUND` |
| 403 | `READONLY_CLIENT_APPLICATION` |
| 400 | `REQUEST_TOO_COMPLEX` |
| 404 | `ROUTE_NOT_FOUND` |
| 503 | `SERVICE_UNAVAILABLE` |
| 503 | `OVER_CAPACITY` |
| 400 | `SPEND_EXCEEDS_BUDGET` |
| 404 | `TAILORED_AUDIENCE_CHANGE_FILE_NOT_FOUND` |
| 404 | `TAILORED_AUDIENCE_NOT_FOUND` |
| 404 | `TAILORED_AUDIENCE_OR_TAILORED_AUDIENCE_EXPANDED_NOT_FOUND` |
| 404 | `TARGETING_CRITERION_NOT_FOUND` |
| 400 | `TOO_MANY_CAMPAIGNS` |
| 400 | `TOO_MANY_LINE_ITEMS` |
| 429 | `TOO_MANY_REQUESTS` |
| 400 | `TV_SHOW_OUTSIDE_MARKET` |
| 400 | `TWEET_CANNOT_BE_BLANK` |
| 403 | `TWEET_IS_SPAM` |
| 404 | `TWEET_NOT_FOUND` |
| 429 | `TWEET_RATE_LIMIT_EXCEEDED` |
| 401 | `UNAUTHORIZED_ACCESS` |
| 403 | `UNAUTHORIZED_CLIENT_APPLICATION` |
| 400 | `UNKNOWN_CARD_TYPE` |
| 400 | `UNKNOWN_CRITERIA_TYPE` |
| 403 | `USER_NOT_FOUND` |
| 404 | `WEB_EVENT_TAG_NOT_FOUND` |
# Ads API hierarchy and terminology
Source: https://docs.x.com/x-ads-api/fundamentals/hierarchy-and-terminology
To be successful on the Ads API, it’s important to understand how entities in X Ads relate to each other. This tutorial goes over the basics of the X Ads object hierarchy.
## Ad Group (line items)
Ad groups, known as [line items](https://developer.x.com/content/developer-twitter/en/docs/tutorials/ads-api-hierarchy-terminology#line-items) on the Ads API, exist under campaigns and are used for targeting and bidding against a set of X users. Advertisers promote posts or media (e.g., videos that are promoted as In-stream ads) by associating them with a line item. Also see Ad Group.
## Account Media
A collection of creatives that have been uploaded to an ads account as [account media](/x-ads-api/creatives#account-media) that can include promoted video [pre-roll assets](/x-ads-api/campaign-management#video-views-preroll-objective), also referred to as in-stream ads, and images that can be promoted on the [X Audience Platform](https://developer.x.com/content/developer-twitter/en/docs/ads/measurement/overview/twitter-audience-platform).
## Ads Accounts
At the top of the X Ads hierarchy are ads accounts. An ads account can be managed by multiple X users. @Furni, our demo furniture store, would be an example of a user who manages an ads account. We identify ads accounts by an account\_id, which is a [base36](https://en.wikipedia.org/wiki/Base36) alpha-numeric string.
Under each account, we store a number of entity types that can be reused across campaigns, such as tailored audiences that can be used for targeting, account media, which are videos or images, and cards, which are expanded creatives that you can add to a post.
## Amplify Video
When uploading a video asset, the uploading entity can define a category for the video (e.g., Tweet Video, Tweet Gif, Tweet Image and Amplify Video). The amplify video category is required when trying to upload a video that is to be served as an in-stream advertisement. These videos require special processing to ensure that they’re servable and hence the media category of Amplify Video is required.
## Analytics
Analytics metrics help partners and advertisers understand the performance of the content they promote on X. This includes information such as impressions, clicks, video views, and spend. In addition, partners and advertisers are able to get detailed metrics for various segments of the audiences they reach.
The Ads API supports two ways of retrieving detailed campaign performance metrics: synchronously and asynchronously.
With [synchronous analytics](/x-ads-api/analytics#synchronous-analytics) requests, the requested metrics are returned in the response. The synchronous endpoint supports short time ranges and is ideal for querying real-time campaign performance.
With the [asynchronous analytics](/x-ads-api/analytics#asynchronous-analytics) endpoints, the requested metrics are available in a downloadable results file after the associated "job" has finished processing. The asynchronous endpoints support requesting metrics over a much longer time range, allows returning segmented data, and are intended for fetching much more data -- ideal for generating reporting or historical backfills.
## Campaigns
Each campaign that the advertiser runs must be created under an existing funding instrument. A campaign lets you define things like the name, schedule, and budget of an ad campaign. In sticking with the example of Furni, we might create a campaign called “Furni home decor”.
It’s worth noting that an ads account is limited to a max of 200 active Campaigns; this limit can be elevated by the advertiser’s account manager. A Campaign is deemed active until its end time is reached or its budget is exhausted. A paused campaign is still considered an active campaign for the purposes of campaign limits.
## Cards
Cards offer a way to visually extend a Tweet to include an image, video or UI elements. The Ads API supports several card types that can be used in Tweets, which can then be promoted in campaigns.
## Creatives
Advertisers can promote Tweets in campaigns that include creatives, such as images, GIFs, and video. These creatives can be associated with X cards that allow attaching rich photos, videos and media experiences to Tweets. Creatives can also be directly attached to Tweets. For example, you can include text and a video (or up to 3 images) and create a promoted Tweet.
Each line item needs to have at least one creative associated with it in order to run. Several options for creatives are available, including Promoted Accounts for gaining new followers, Media Creatives such as an image or video for line items across the TX Audience Platform, or Promoted Posts.
## Funding Instruments
Also under the ads account are funding instruments, which are the different sources of funding the advertiser has set up to use with X Ads. These span from insertion orders that they’ve signed with X to a credit card that is attached to the account.
## Line Items
Within a campaign, you can have one or more ad groups, also known as line items in the Ads API. Line items can be thought of as different segments of a campaign, each with its own targeting set and its own creative. Campaigns that contain multiple line items are often referred to as “ad group campaigns”.
One of the benefits of multiple line items within a single campaign is that you can create a greater variety of targeting and creative combinations.
Under our “Furni home decor” campaign, we might want to create two line items: one could be “Home buyers in San Francisco”, and the other could be “Home buyers in London”.
Up to 100 line items are allowed per campaign, and an ads account is limited to 4,000 active line items in total across all campaigns.
## Mobile App Promotion (MAP)
Mobile App Promotion, or MAP, is a suite of products that enable advertisers to promote mobile apps via X These include app installs, conversions and re-engagement.
## Mobile App Conversion Tracking (MACT)
X mobile app promotion measurement allows advertisers to track the success of advertising campaigns on X that are designed to drive installs or other in-app conversions. An X mobile measurement partner provides the ability for an advertiser to manage what conversions they want to track from the apps they are promoting on X. MACT Overview
## Media Library
The Media Library endpoints provide the ability to manage images, GIFs, and videos for X Ads accounts. Media assets in the library can be used in posts and to create cards. They can also be reused in multiple creatives, eliminating the need to upload the same asset multiple times.
## Promoted Accounts
Promoted Accounts (followers campaigns) are part of Who to Follow, which suggests accounts that people don’t currently follow and may find interesting. Promoted Accounts help introduce an even wider variety of accounts people may enjoy.
Promoted Accounts allow advertisers to promote their account and grow their audience on X. Follower campaigns are displayed in multiple locations across the X platform — including Home Timelines, Who to Follow, and search results — and this suggestion is labeled as Promoted to distinguish it from other recommended accounts.
## Promotable Users
Each X Ads account can have one or more promotable users, which are users that we can promote through the ads account. Furni’s @Furni handle would be an example of a FULL promotable user under Furni’s ads account, which means we can run all types of campaigns for @Furni and their tweets. There can only be one FULL promotable user for an ad account.
Note there can also be other promotable under an ads account. For example, if we wanted to promote @Jack’s Tweets about Furni products, he would become a retweet-only promotable user on the account which is indicated by RETWEETS\_ONLY. Advertisers should contact their X account manager for information about adding reweet users to their ads account.
## Promoted Video
Promoted videos are videos within Promoted Tweets that are paid for by advertisers. These appear in the Home timeline, at the top of search results on X, and elsewhere on the platform, and are clearly marked as "Promoted”.
## Publisher Network
See [X Audience Platform](/x-ads-api/audiences).
## Scheduled Tweets
Scheduled Tweets allow an advertiser or user to create a Tweet that can be scheduled to go live at a later date. In addition to being able to create and manage these Tweets, the API allows the ability to associate these Tweets with a line item, to be promoted once the Tweet goes live. This allows advertisers to stage create native Tweets and plan their campaign creatives in advance of any key initiatives. For example, staging a Tweet creative to live immediately upon a new product announcement.
## Segmentation
Segmentation allows partners and advertisers to retrieve metrics broken out particular targeting values -- such as age, devices, or languages -- and is only available through our asynchronous analytics endpoints. To request segmented metrics, use the segmentation\_type request parameter. For more details on segmentation options, see Metrics and Segmentation.
## Tailored Audience - List
Tailored audiences from lists are one of three types of Tailored Audiences, created by uploading a file containing your own user and customer data. Your lists are matched with users on X so that you can directly target them in your campaigns. Please review these restrictions.
## Tailored Audience - Web
Tailored Audience from web, one of three types of Tailored Audiences, is a collection X users who have visited your website. To use Tailored Audiences from web you must have our X pixel installed on your website, or use one of our accepted tag manager partners. Please review these restrictions.
## Targeting Criteria
As we mentioned previously, targeting criteria are associated with a line item. We have a variety of different targeting that you can use, from location, keywords, and gender to more granular attributes, such as user behaviors and interests. For the “Home Buyers in San Francisco” line item, we might target the “home buying” behavior along with the “San Francisco” location.
For information on the different types of targeting available, visit the Targeting Overview page on our developer site.
## Twitter Object Nest (TON)
The Twitter Object Nest (TON) holds media and various assets upload via the Media Upload endpoints to be used as Creatives.
## Creatives
Each line item needs to have at least one creative associated with it in order to run. Several options for creatives are available, including Promoted Accounts for gaining new followers, Media Creatives such as an image or video for line items across the X Audience Platform, or Promoted Posts. Here’s an example post that @Furni could promote and use as a creative.
# Making Authenticated Requests
Source: https://docs.x.com/x-ads-api/fundamentals/making-authenticated-requests
Accessing the X Ads API endpoints requires your application to send authenticated web requests securely using TLS to [https://ads-api.x.com](https://ads-api.x.com).
The following sections will provide an overview of making authenticated API requests, setting up [Twurl](https://github.com/twitter/twurl#getting-started) to interact with the API, and extending your application to support OAuth 1.0a and make requests against your Ads account.
## Requirements
Before making authenticated requests to the X Ads API, you will need:
* an [approved developer account](/resources/fundamentals/developer-portal)
* an application that has been [approved for Ads API](/x-ads-api/introduction) access
* API key and secret obtained through the [app management UI](/resources/fundamentals/developer-apps) and
* [access tokens](/resources/fundamentals/authentication#obtaining-access-tokens-using-3-legged-oauth-flow) for a user with access to a X Ads account
## Using the API
The Advertising API is accessed on [https://ads-api.x.com](https://ads-api.x.com). The [standard REST API](https://developer.x.com/en/docs/x-api/v1/tweets/post-and-engage/overview), and the Advertising API can be used together with the same client app. The Advertising API enforces HTTPS, therefore attempts to access an endpoint with HTTP will result in an error message.
The Ads API outputs JSON. All identifiers are strings and all strings are UTF-8. The Advertising API is [versioned](/x-ads-api/fundamentals/versioning) and the version is specified as the first path element of any resource URL.
`https://ads-api.x.com/
### Overview
Clicking on one of the streams in the main dashboard will take you to an overview page for that stream.
For streaming delivery products, this page includes the following:
1. A volume chart of the number of activities being delivered to you through each specific stream connection
2. Details (connection ID and IP address) on currently active connections on the stream
3. A log of recent connection, disconnection, and rule-update events for your stream
Note that the scale of the chart may be adjusted with the links in the top-right corner. The visibility of individual connections and disconnections can be toggled by clicking the appropriate key in the legend directly below the chart.
### Connections
The Connections page provides details on recent connection events on your stream. This includes the start and end times for each connection (in 24 hour UTC), the duration of each connection, the IP of the server that made the connection, a unique connection ID for reference purposes, and the current connection status. The status corresponds to the most recent event for the specified connection – i.e. Client Connected, or a disconnect, with the type of disconnect specified. For more details on connection debugging, visit the [disconnections explained guide](/x-api/enterprise-gnip-2.0/powertrack-api#integrating-with-powertrack).
### API Help
The API Help page provides the API endpoint URLs for your stream, as well as the Rules API endpoint for the stream, where applicable. In addition, it includes sample curl commands and instructions on how to connect to the stream endpoint, and how to programmatically add, delete, and list rules from your stream's Rules API endpoint.
### Rules
The Rules tab is available for PowerTrack streams, and provides a quick way to get started by manually entering plain text rules via a user interface. Note that the interface only supports adding up to 1000 rules via this manual method, and should be only used for initial testing. We recommend managing your rules programmatically via the [Rules API](/x-api/enterprise-gnip-2.0/powertrack-api#api-reference-index) in any production setting.
### Settings
The Settings tab allows you to switch the output format of the data in your stream, where multiple format options are supported. To switch the format, just use the radio buttons indicating the different options. The change will take effect upon reconnecting to the stream. Note that updating this setting will take place immediately on the next request or connection and may break your parser with the new format.
**Please note:** The recommended setting for getting the most data is "Leave data in the original format" which will return data in the enriched native format [here](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary#post-object). Activity streams format is described [here](/x-api/enterprise-gnip-2.0/fundamentals/data-dictionary#activity-object).
## Usage tab
The Usage Tab provides insight into your use of your streams over various time periods. For programmatic access to usage information, see the [Usage API](/x-api/enterprise-gnip-2.0/fundamentals/usage).
### Monthly
The Monthly Usage page displays your stream usage broken down by product. For example, coverage products (for example, PowerTrack, Historical PowerTrack, and PowerTrack Replay) for a given data source will be grouped together to provide separate data, as well as a combined roll-up count. The counts include a current month-to-date, estimated end-of-month (based on this month’s usage so far, and remaining time in the month), and the previous two months’ counts.
Notably, these counts are deduplicated for each product and stream. If you received the same Post through multiple connections to the same PowerTrack stream, that Post will be counted once for these purposes. Counts will be updated every 24 hours at 00:00 UTC.
### Daily
The Daily Usage page provides daily deduplicated counts for each day in the current month, broken down by product. Counts are updated every 24 hours at 00:00 UTC.
### Rules
Rule limits are based on your contracted PowerTrack rule package and are applied across all streams of a given "type". Counts are updated whenever a new rule is added or deleted.
## Account tab
### My Profile
View details about your individual user profile, and change your password here. Additionally, you may configure account usage threshold notices specific to your account. API status notices are available through the status page at [https://api.twitterstat.us](https://api.twitterstat.us).
### Account Settings
You may add, remove, and edit users, and configure email notifications for individual users and usage threshold alerts.
Please note that there are three types of users – Account Admin, User, and Email Only.
* Account admins are allowed to create/delete/edit other users, and can use basic authentication with username (email) and password to connect to the enterprise APIs
* Users cannot create or modify other users, but can use basic authentication with username (email) and password to connect to the enterprise APIs
* Email Only users do not have access to the dashboard, are not authorized to connect to the enterprise APIs and only receive notifications, if they are configured to receive them in the Notifications section.
### Usage Thresholds
Configure volume thresholds for your products. These will initiate email alerts for the users who have configured those notifications in their profiles, both for the warning threshold and critical threshold for each product.
Please note that these thresholds are evaluated once per day at 19:30 (UTC), and are not evaluated in real-time.
# Rate limits: Enterprise
Source: https://docs.x.com/x-api/enterprise-gnip-2.0/fundamentals/rate-limits
## Overview
Every day many thousands of developers make requests to the X API. To help manage the sheer volume of these requests, limits are placed on the number of requests that can be made. These limits help us provide the reliable and scalable API that our developer community relies on.
The maximum number of requests that are allowed is based on a time interval, some specified period or window of time. If an endpoint has a rate limit of 900 requests/15-minutes, then up to 900 requests over any 15-minute interval is allowed.
### Enterprise rate limits per window
| Product | Endpoint | Rate limit |
| :------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------ |
| PowerTrack API | Streaming endpoint | 60 requests per minute |
| Rules endpoint | 60 requests per minute aggregated across all /rules endpoints | |
| Replay endpoint | 5 requests per 5 minutes | |
| Historical PowerTrack API | | 60 Jobs can be created per (UTC) day. |
| | 30 Jobs can be created per hour. | |
| | 2 Jobs can be estimating concurrently. | |
| | 2 Jobs can be running concurrently. | |
| Decahose API | | 10 requests per minute |
| Streaming likes API | | 10 requests per minute |
| Firehose API | | 10 requests per minute |
| Account Activity API | POST account\_activity/webhooks | 15 requests per 15 minutes |
| GET account\_activity/webhooks | 15 requests per 15 minutes | |
| PUT account\_activity/webhooks/:webhook\_id | 15 requests per 15 minutes | |
| POST account\_activity/webhooks/:webhook\_id/subscriptions/all | 500 requests per 15 minutes | |
| GET account\_activity/subscriptions/count | 15 requests per 15 minutes | |
| GET account\_activity/webhooks/:webhook\_id/subscriptions/all | 500 requests per 15 minutes | |
| GET account\_activity/webhooks/:webhook\_id/subscriptions/all/list | 50 requests per 15 minutes | |
| DELETE account\_activity/webhooks/:webhook\_id | 15 requests per 15 minutes | |
| DELETE /account\_activity/webhooks/:webhook\_id/subscriptions/:user\_id/all.json | 500 requests per 15 minutes | |
| Replay | 5 requests per 15 minutes | |
| Search API | | Per minute rate limit will vary by contract |
| | 20 requests per second aggregated across either the 30 day data and counts endpoints, or across the full-archive data and counts endpoints | |
| Engagement API | | Per minute rate limit will vary by contract |
| Compliance Firehose API | | 10 requests per minute |
| Usage API | | 2 requests per minute |
# Rules and filtering: Enterprise
Source: https://docs.x.com/x-api/enterprise-gnip-2.0/fundamentals/rules-filtering
## Getting started with enterprise rules and queries
Products utilizing enterprise operators deliver social data to you based on filtering rules you set up. Rules are made up of one or more ‘clauses’, where a clause is a keyword, exact phrase, or one of the many enterprise operators. Before beginning to build rules with enterprise operators, be sure to review the syntax described below, look through the list of available operators, and understand the restrictions around building rules. You should also be sure to understand the nuances of how rules are evaluated logically, in the "[Order of operations](#orderofoperations)" section.
Multiple clauses can be combined with both "and" and "or" logic.
**Please note:** "And" logic is specified with a space between clauses, while or logic is specified with an upper-case `OR`.
Each rule can be up to 2,048 characters long with no limits on the number of positive clauses (things you want to match or filter on) and negative clauses (things you want to exclude and not match on).
### Building rules and queries
**Keyword match**
Keyword matches are similar to queries in a search interface. For example, the following enterprise operator rule would match activities with the term "social" in the text body.
`social`
**ANDing terms with white space**
Adding another keyword is the same as adding another requirement for finding matches. For example, this rule would only match activities where both "social" and "media" were present in the text, in either order – *having a space between terms operates as boolean AND logic*. If you include an explicit AND in your rule, it will rejected by the rules endpoint.
`social media`
**ORing terms with upper-case OR**
Many situations actually call for boolean OR logic, however. This is easily accomplished as well. *Note that the OR operator must be upper-case and a lower-case ‘or’ will be treated as a regular keyword.*
`social OR data`
**Negating terms**
Still other scenarios might call for excluding results with certain keywords (a boolean NOT logic). For instance, activities with ‘happy’, but excluding any with ‘birthday’ in the text.
`social -personality`
**Grouping with parentheses**
These types of logic can be combined using grouping with parentheses, and expanded to much more complex queries.
`(social OR data) (academic OR research) -personality -information -university`
This is just the beginning though – while the above examples rely simply on tokenized matching for keywords, enterprise products also offer operators to perform different types of matching on the text.
**Exact match**
`"social media research"`
**Substring match**
`contains:info`
**Proximity match**
`"social media research"~3`
Further, other operators allow you to filter on unique aspects of social data, besides just the text.
**The user who is posting a Post**
`from:XDeveloeprs`
**Geo-tagged Tweets within 10 miles of Pearl St. in Boulder, CO, United States**
`point_radius:[-105.27346517 40.01924738 10.0mi]`
**Putting it all together**
These can be combined with text filters using the same types of logic described above.
`(social OR data) (academic OR research OR "social media research") point_radius:[-105.27346517 40.01924738 10.0mi] lang:en -personality -information -university`
### Boolean Syntax
The examples in the previous section, utilized various types of boolean logic and grouping. See the table below for additional detail regarding the syntax and requirements for each.
| | | |
| :------------- | :---------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Logic type** | **Operator syntax** | Description |
| AND | social data | Whitespace between two operators results in AND logic between them 
This can also be found under the rules section of the usage tab (see below).
**What If I Hit My Cap?**
If you attempt to upload more rules to your stream that you are contractually allowed, you will receive the following message:
*“Request exceeds account’s Rule Limit. Delete rules or contact your account manager to proceed.”*
If you encounter this error message while you have an open connection, your stream will not be disrupted. In order to add more rules once you hit your cap, you will either need to delete rules from your stream or reach out to your account manager to increase your contractual limit.
### Recovery and redundancy features
#### Introduction
With streaming high volumes of realtime Posts comes a set of best practices that promote both data reliability and data full-fidelity. When consuming realtime data, maximizing your connection time is a fundamental goal. When disconnects occur, it is important to automatically detect that and reconnect. After reconnecting it’s important to assess if there are any periods to backfill data for. The component that manages these details and consumes realtime Posts is only one part of a system with network, datastore, server, and storage concerns. Given the complexity of these systems, another best practice is to have different streaming environments, with at least separate streams for development/testing and production.
PowerTrack comes with a set of features that help with these efforts.
To support multiple environments, we can deploy [Additional Streams](/x-api/enterprise-gnip-2.0/powertrack-api#recovery-and-redundancy-features) for your account. These streams are completely independent of each other, having unique URLs and separate rule sets.
To help support maintaining a connection, each realtime PowerTrack stream supports [Redundant Connections](/x-api/enterprise-gnip-2.0/powertrack-api#redundant-connections). The most common architecture is for a stream to have two connections, and on the client-side there are two independent consumers, ideally on different networks. With this design, there can be redundancy across the client-side networks, servers, and datastore pathways. Note that a full-copy of the data is served on each connection (since there is a single ‘source’ server and no partitioning with filtered streams) and the client-side must be tolerant of and manage these duplicate data.
For detecting disconnects, each stream has a ‘heartbeat’ signal that can used to detect when a stream has timed-out. These 10-second heartbeats provide connection confirmation even when there are time periods with no Posts matching your rules and being delivered on your stream. For most X stream consumers, the data volumes are high enough that even a smaller duration of no Posts is a sign of a connection issue. So both a ‘data silence’ and lack of a heartbeat can be used to detect a disconnect.
Since disconnects will happen, PowerTrack has a dedicated [Recovery](/x-api/enterprise-gnip-2.0/powertrack-api#replay-api) and a PowerTrack [Backfill](/x-api/enterprise-gnip-2.0/powertrack-api#backfill) feature to help recover data that was missed due to disconnections and other operational issues. To learn more about disconnects see our support article [HERE](/x-api/enterprise-gnip-2.0/powertrack-api#disconnections-explained).
#### Additional streams
Having additional PowerTrack streams is another way to help build reliability into your solution. So much so that it is considered a best practice. Any additional streams are completely independent, having their unique endpoint and independent rule set. Each stream is assigned its own ‘label’, and this label, along with your account name, are part of that stream’s URL.
[https://gnip-stream.x.com/stream/powertrack/accounts/\{ACCOUNT\\\_NAME}/publishers/twitter/\{STREAM\\\_LABEL}.json](https://gnip-stream.x.com/stream/powertrack/accounts/\{ACCOUNT\\_NAME}/publishers/twitter/\{STREAM\\_LABEL}.json)
The most common convention is to have a realtime stream dedicated for your production system, and an additional stream available for development and testing. Having a test/development stream enables PowerTrack customers to have a stream to test client consumer updates. While any (unique) label can be assigned to a stream, one convention is to use ‘prod’ for production stream, and ‘dev’ or ‘sandbox’ for an additional development stream.
The number of streams, and their unique labels, is configurable by your account representative.
#### Redundant connections
A redundant connection simply allows you to establish more than 1 simultaneous connections to the data stream. This provides redundancy by allowing you to connect to the same stream with two separate consumers, receiving the same data through both connections. Thus, your app has a hot failover for various situations, e.g. where one stream is disconnected or where your app’s primary server fails.
The number of connections allowed for any given stream is configurable by your account representative. To use a redundant stream, simply connect to the same URL used for your primary connection. The data for your stream will be sent through both connections, with both stream connections represented on the stream dashboard.
Note that for billing purposes, we deduplicate the activity counts you receive through multiple connections such that you are only billed for each unique activity once.
#### Recovery
#### Overview
Recovery is a data tool that provides streaming access to a rolling window of recent X historical data. It should be utilized to recover data in scenarios where your consuming application misses data in the real time stream, whether due to disconnecting for a short period, or for any other scenario where you fail to ingest realtime data for a period of time.
There are different varieties of Recovery streams, corresponding to different types of realtime streams that they complement. PowerTrack Recovery streams are provided to allow customers using realtime PowerTrack to recover data they miss, using the same rules as they use in realtime.
#### Using Recovery
With the Recovery stream, your app can make requests to it that operate in the same manner as requests to existing realtime streams. However, your app must specify parameters in the URL that indicate the time window you are requesting. In other words, a Recovery request asks for “Posts from time A to time B.” These Posts are then delivered through your streaming connection in a manner that mimics the realtime stream.
Posts are delivered beginning with the first minute of the specified time period, continuing until the final minute is delivered. At that point, a “Recovery Request Completed” message is sent through the connection, and the connection is then closed by Gnip. If your request begins at a time of day where little or no matching results occurred, there will likely be some period of time before the first results are delivered – data will be delivered when Recovery encounters matches in the portion of the archive being processed at that time. When no results are available to deliver, the stream will continue sending carriage-return “heartbeats” through the connection to prevent you from timing out.
Recovery is intended as a tool for easily recovering data missed due to short disconnects, not for very long time periods like entire days. If the need to recover data for long periods arises, we recommend breaking longer requests into shorter time windows (e.g. two hours) to reduce the possibility of being disconnected mid-request due to internet volatility or other reasons, and to provide more visibility into the progress of long requests.
#### Data availability
You can use the Recovery feature to recover missed data within the last 24 hours if you are unable to reconnect with the 5 minute backfill window.
The streaming recovery feature allows you to have an extended backfill window of 24 hours. Recovery enables you to ‘recover’ the time period of missed data. A recovery stream is started when you make a connection request using 'startTime' and 'endTime' request parameters. Once connected, Recovery will re-stream the time period indicated, then disconnect.
You will be able to make 2 concurrent requests to recovery at the same time, i.e. “two recovery jobs”. Recovery works technically in the same way as backfill, except a start and end time is defined. A recovery period is for a single time range.
| Name | Type | Description |
| :-------- | :-------------- | :---------------------------------------------------------------------------------------------------------- |
| startTime | date (ISO 8601) | YYYY-MM-DDTHH:mm:ssZ (ISO 8601/RFC 3339).
Give it a name, select the appropriate use-case, and provide a Project description. Next, you can either create a new App, or connect an existing [App](/resources/fundamentals/developer-apps) (an App is a container for your API keys that you need in order to make an HTTP request to the X API).
Click ‘create a new App instead’ and give your App a name in order to create a new App.
Once you click complete, you will get your API keys and the bearer token that you can then use to connect to the new endpoints in the X API v2.
Click the (+) next to API key, API secret key and Bearer token and copy these values to a safe place on your local machine. You will need these to make the API calls in the next step.
Note: The keys in the screenshot above are hidden, but in your own developer portal, you will be able to see the actual values for the API key, API secret key and Bearer token.
## How to get the user ID for a user to use in the user Tweet timeline and user mention timeline endpoints
The user Tweet timeline and user mention timeline endpoints allow you to get Posts using the user ID. In order to get the user ID from a username, you can use the new [user lookup endpoint v2](/x-api/users/lookup/quickstart/user-lookup). Replace the USER\_NAME with the username of your choice and XXXX with your own bearer token that you obtained above
```bash
curl --request GET 'https://api.x.com/2/users/by/username/USER_NAME --header 'Authorization: Bearer XXXXXX'
```
You will see the user ID in response as shown below:
```json
{
"data": {
"id": "2244994945",
"name": "Developers",
"username": "XDevelopers"
}
}
```
## Connecting to the user Tweet timeline and user mention timeline endpoints
In order to get the user Tweet timeline for a user ,run the following curl command in your terminal (make sure to replace the USER\_ID with the user ID of your choice and XXXX with your own bearer token that you obtained above)
```bash
curl --request GET 'https://api.x.com/2/users/USER_ID/tweets' --header 'Authorization: Bearer XXXXXX'
```
You will see that the JSON response for these requests contains the ID and text for the Posts by default (example below).
```yaml
{
"id": "1334200897081987072",
"text": "👀 If you are new to the X API v2, check out this step-by-step guide to making your first request https://t.co/4rZqThpSbp"
}
```
If you want additional fields returned as part of the response (such as user information, additional Tweet fields such as context annotations etc.) then you will need to specify those fields explicitly in your response. Learn how to do this from the [guide on using fields and expansions](/x-api/fundamentals/data-dictionary#how-to-use-fields-and-expansions).
You can also get these Posts using programming languages of your choice. Check out our sample code in Python, Node (JavaScript), Java and Ruby for the user Tweet timeline and user mention timeline endpoints on our [Github repository](https://github.com/xdevplatform/Twitter-API-v2-sample-code).
## Exploring the user’s Posts
Once you know how to get Posts using the user Tweet timeline and user mention timeline endpoints, you can start to explore their Posts. For example, if you wanted to identify common named entities present in a user’s mentions, you can do the following:
In the API request, specify that you want the context\_annotations object returned in the Tweet responses:
```bash
curl --request GET 'https://api.x.com/2/users/USER_ID/mentions?tweet.fields=context_annotations' --header 'Authorization: Bearer XXXXXX'
```
In the response, you will see if any named entities are present in the mentions. Here is an example:
```json
{
"domain": {
"id": "47",
"name": "Brand",
"description": "Brands and Companies"
},
"entity": {
"id": "783214",
"name": "X"
}
}
```
If you wanted to see which popular entities appear in your mentions, you could keep a count of popular entities by parsing each Tweet in the mentions.
If you wanted to explore the preview image URL for all Posts in your timeline that contain media, you can do the following:
In the API request, specify that you want the preview\_image\_url in the tweet.media fields, and the attachments.media\_keys expansions
```bash
curl --request GET 'https://api.x.com/2/users/2244994945/mentions?max_results=100&media.fields=preview_image_url&expansions=attachments.media_keys' --header 'Authorization: Bearer XXXXXX'
```
In the response, you will see the preview\_image\_url in the includes object as shown below:
```json
{
"includes": {
"media": [
{
"media_key": "16_1334657439640121344",
"preview_image_url": "https://pbs.twimg.com/tweet_video_thumb/EoWn3rqU8AAtFWL.jpg",
"type": "animated_gif"
}
]
}
}
```
Once you have an understanding of how to navigate a user’s Posts, you can also use other APIs and services to do more with the Posts. Below are some resources to keep handy when using the user Tweet timeline and user mention timeline endpoints.
## Resources
* Learn more about the [user Tweet timeline and the user mention timeline endpoints](/x-api/posts/timelines/introduction).
* Check out the [API reference for the user Tweet timeline endpoint](/x-api/posts/user-posts-timeline-by-user-id) to learn more about what’s available.
* Check out the [API reference for the user mention timeline endpoint](/x-api/posts/user-mention-timeline-by-user-id) to learn more about what’s available.
* Get inspired by reading our other [tutorials](/tutorials).
# Getting historical Posts using the v2 full-archive search endpoint
Source: https://docs.x.com/tutorials/getting-historical-posts-using-the-full-archive-search-endpoint
## Introduction
The [Search Posts endpoints](/x-api/posts/search/introduction)
in the v2 world enable you to receive Posts related to topics of interest,
based on a search query that you produce. We have two different endpoints
available with v2 Search Posts: recent search, which is available to all
developers with an approved account and can search for Posts up to seven days
old, and full-archive search, which is only available to
researchers approved for the
[Academic Research product track](https://developer.x.com/en/products/x-api/early-access/guide#na_2),
and can search through the entire archive of Posts dating back to March 2006.
You can see our full search offering on our
[search overview page](/x-api/posts/search/introduction).
These Search Posts endpoints address one of the most common use cases for
academic researchers, who might use this for longitudinal studies, or analyzing
a past topic or event.
This tutorial provides a step-by-step guide for researchers who wish to use the
full-archive search endpoint to search the complete history of public X
data. It will also demonstrate the different ways to build a dataset, such as by
retrieving geo-tagged Posts, and how to page through the available Posts for a
query.
### Prerequisites
Currently, this endpoint is only available as part of the
[Academic Research product track](https://developer.x.com/en/solutions/academic-research/products-for-researchers).
In order to use this endpoint, you must
[apply for access](https://developer.x.com/en/portal/petition/academic/is-it-right-for-you).
Learn more about the
[application and requirements for this track](https://developer.x.com/en/solutions/academic-research/application-info).
### Connect an app to the academic project
Once you are approved to use the Academic Research product track, you will see
your Academic [Project](/resources/fundamentals/projects) in the
[developer portal](https://developer.x.com/en/portal/dashboard). From the
"Projects and Apps" section, click on "Add App" to connect your
[X App](/resources/fundamentals/developer-apps) to the Project.
[](https://res.cloudinary.com/practicaldev/image/fetch/s--gHFOyuDc--/c_limit%2Cf_auto%2Cfl_progressive%2Cq_auto%2Cw_880/https://dev-to-uploads.s3.amazonaws.com/i/gb7aevhqyfvfjznd0pnd.png)
Then, you can either choose an existing App and connect it to your project (as
shown below).
Or you can create a new App, give it a name and click complete, to connect a new
App to your Academic Project.
This will give you your API keys and
[Bearer Token](/resources/fundamentals/authentication#using-and-generating-an-app-only-bearer-token) that you can
then use to connect to the full-archive search endpoint.
**Please note**
The keys in the screenshot above are hidden, but in your own developer portal,
you will be able to see the actual values for the API Key, API Secret Key, and
Bearer Token. Save these keys and the Bearer Token because you will need those
for calling the full-archive search endpoint.
### Connecting to the full-archive search endpoint
The cURL command below shows how you can get historical Posts from @XDevelopers
handle. Replace the \$BEARER\_TOKEN with your own Bearer Token, paste the full
request in your terminal, and press "return".
```bash
curl --request GET 'https://api.x.com/2/tweets/search/all?query=from:xdevelopers' --header 'Authorization: Bearer $BEARER_TOKEN'
```
You will see the response JSON.
By default, only the 10 most recent Posts will be returned. If you want more
than 10 Posts per request, you can use the max\_results parameter and set it to
a maximum of 500 Posts per request, as shown below:
```bash
curl --request GET 'https://api.x.com/2/tweets/search/all?query=from:xdevelopers&max_results=500' --header 'Authorization: Bearer $BEARER_TOKEN'
```
###
Building queries
As you can see in the example calls above, using the query parameter, you can
specify the data that you want to search for. As an example, if you wanted to
get all Posts that contain the word *covid* or the word *coronavirus*, you can
use the OR operator within brackets, and your query can be
`(covid OR coronavirus)` and thus your API call will look like the following:
```bash
curl --request GET 'https://api.x.com/2/tweets/search/all?query=(covid%20OR%20coronavirus)&max_results=500' --header 'Authorization: Bearer $BEARER_TOKEN'
```
Similarly, if you want all Posts that contain the words *covid19* that are not
reposts, you can use the is:retweet operator with the logical NOT (represented
by -), so your query can be covid19 -is:retweet and your API call will be:
```bash
curl --request GET 'https://api.x.com/2/tweets/search/all?query=covid19%20-is:retweet&max_results=500' --header 'Authorization: Bearer $BEARER_TOKEN'
```
Check out
[this guide for a complete list of operators](/x-api/posts/search/integrate/build-a-query)
that are supported in the full-archive search endpoint.
### Using the start\_time and end\_time parameters to get historical Posts
When using the full-archive search endpoint, by default Posts from the last 30
days will be returned. If you want to get Posts that are older than 30 days,
you can use the start\_time and end\_time parameters in your API call. These
parameters must be in a valid RFC3339 date-time format, for example
2020-12-21T13:00:00.00Z. Thus, if you want to get all Posts from the XDevelopers
account for the month of December 2020, your API call will be:
```bash
curl --request GET 'https://api.x.com/2/tweets/search/all?query=from:XDevelopers&start_time=2020-12-01T00:00:00.00Z&end_time=2021-01-01T00:00:00.00Z' --header 'Authorization: Bearer $BEARER_TOKEN'
```
###
Getting geo-tagged historical Posts
Geo-tagged Posts are Posts that have geographic information associated with
them such as city, state, country etc.
#### Using has:geo operator
If you want to get Posts that have geo data, you can use the has:geo operator.
For example, the following cURL request will get only those Posts from the
@XDevelopers handle that have geo data:
```
curl --request GET
'https://api.x.com/2/tweets/search/all?query=from:xdevelopers%20has:geo' --header
'Aubashthorization: Bearer $BEARER_TOKEN'
```
#### Using place\_country operator
Similarly, you can limit Posts that have geo data, to a specific country, using
the place\_country operator. The cURL command below will get all Posts from the
@XDevelopers handle from the United States:
```
curl --request GET
'https://api.x.com/2/tweets/search/all?query=from:xdevelopers%20place_country:US'
--hbasheader 'Authorization: Bearer XXXXX'
```
The country is specified above using the ISO alpha-2 character code. Valid ISO
codes can be found [here](http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).
### Getting more than 500 historical Posts using the next\_token
As mentioned above, by default you can only get up to 500 Posts per request for
a query to the full-archive search endpoint. If there are more than 500 Posts
available for your query, your json response will include a next\_token which you
can append to your API call in order to get the next available Posts for this
query. This next\_token is available in the meta object of your JSON response,
which looks something:
```
{ "newest_id": "12345678...", "oldest_id": "12345678...", "result_count": 500,
"nebashxt_token": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" }
```
Hence, to get the next available Posts, use the next\_token value from this meta
object and use the value as the value for the next\_token in your API call to the
full-archive search endpoint as shown below (You will use your own Bearer Token
and the value that you get for the Next Token for your previous API call).
```
curl --request GET
'https://api.x.com/2/tweets/search/all?max_results=500&query=covid&next_token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
--header 'Authorization: Bearer $BEARER_TOKEN'
```
This way, you can keep checking if a next\_token is available and if you have not
reached your desired number of Posts to be collected, you can keep calling the
full-archive endpoint with the new next\_token for each request. Keep in mind
that full-archive search endpoint counts towards your total
[Post cap](/x-api/fundamentals/post-cap), in other words the number of
Posts per month that you can get from the X API per
[Project](/resources/fundamentals/projects), so be mindful of your code logic when paging
through the results in order to make sure you do not end up inadvertently
exhausting your Post cap.
Below are some resources that can help you when using the full-archive search
endpoint. We would love to hear your feedback. Reach out to us on
[@XDevelopers](https://x.com/XDevelopers) or on our
[community forums](https://devcommunity.x.com/) with questions about this
endpoint.
### Additional resources
* [Full-archive search endpoint API reference](/x-api/posts/full-archive-search)
* [Learn the basics of building a search query](/x-api/posts/search/integrate/build-a-query)
# Getting started with Postman
Source: https://docs.x.com/tutorials/postman-getting-started
In this tutorial, we will discuss what Postman is and how to quickly get set up with it.
## Introduction
Postman is a desktop and web application that allows you to make requests to an API from a graphical user interface. We recommend using Postman with the X API, X Ads API, and Labs endpoints when exploring the APIs functionality, as well as when you are troubleshooting issues with your application.
We currently have two Postman collections available:
From the list of environments, click on “X API v2”.
Next, add a variable for all of the different keys and tokens that you’ve generated via the Apps dashboard into the table. Here is an example of what your table should look like:
| VARIABLE | INITIAL VALUE | CURRENT VALUE |
| :--------------- | :---------------------------------------------------------------- | :---------------------------------------------------------------- |
| consumer\_key | `QAktM6W6DF6F7XXXXXX` | `QAktM6W6DF6F7XXXXXX` |
| consumer\_secret | `AJX560A2Omgwyjr6Mml2esedujnZLHXXXXXX` | `AJX560A2Omgwyjr6Mml2esedujnZLHXXXXXX` |
| access\_token | `1995XXXXX-0NGqVhk3s96IX6SgT3H2bbjOPjcyQXXXXXXX` | `1995XXXXX-0NGqVhk3s96IX6SgT3H2bbjOPjcyQXXXXXXX` |
| token\_secret | `rHVuh7dgDuJCOGeoe4tndtjKwWiDjBZHLaZXXXXXX` | `rHVuh7dgDuJCOGeoe4tndtjKwWiDjBZHLaZXXXXXX` |
| bearer\_token | `AAAAAAAAAAAAAAAAAAAAAL9v6AAAAAAA99t03huuqRYg0mpYAAFRbPR3XXXXXXX` | `AAAAAAAAAAAAAAAAAAAAAL9v6AAAAAAA99t03huuqRYg0mpYAAFRbPR3XXXXXXX` |
Note that the keys and tokens used in the above table are made up and will not work if used in a request.
Once you’ve added your credentials as variables and have made sure that the X API v2 environment is selected, you will be ready to make requests to the X API v2 collection. This is because each of the endpoint’s authorization tabs are set up to automatically inherit the variables from this environment.
For using Postman with User Access Tokens skip XXXX to the additional details on how to do so.
### Step three: Select an endpoint
Next step is to choose an endpoint from the collection and start to build your request. You can select an endpoint from the right-hand side navigation. Here is what this looks like:
For this example, we are going to use the X API v2 > Post Lookup > Single Post endpoint.
#### Step four: Add values to the Params tab
Next step will have you navigate to the Params tab. You should see a set of inactive params with descriptions that explain what the parameter does, and a list of all of the potential values that you can pass with your request.
In this example, we are going to activate the expansions and tweet.fields query parameters and add the following values:
| | |
| :------------- | :----------------------- |
| **Key** | **Value** |
| `tweet.fields` | `created_at,attachments` |
| expansions | author\_id |
In addition to adding the query parameters, we need to add the required Path Variable, id. Since this endpoint returns Posts, we need to add a valid Post ID as the value.
You can find the Post ID by navigating to x.com and clicking on a Post, and then looking in the URL. For example, the following URL's Post ID is `1228393702244134912`:
`https://x.com/XDevelopers/status/1228393702244134912`
On the Params tab, scroll down past all of the query parameters to display the “Path Variables” section. We will be adding the Post ID that you would like to use as a value to the id key.
If you’ve entered everything from this step correctly, the Params tab should look like the following:
#### Step five: Send your request and review your response
Now that everything is set up in your request, you can click the “Send” button.
If everything was set up properly, you should receive the following payload:
```json
{
"data": {
"author_id": "2244994945",
"text": "What did the developer write in their Valentine’s card?\n \nwhile(true) {\n I = Love(You); \n}",
"id": "1228393702244134912",
"created_at": "2020-02-14T19:00:55.000Z"
},
"includes": {
"users": [
{
"username": "XDevelopers",
"name": "Developers",
"id": "2244994945"
}
]
}
}
```
### Generating a User Access Token with Postman:
#### Using OAuth 1.0a to generate a user access token
Review the three step process used in the [OAuth1.0a flow test collection](https://www.postman.com/xapidevelopers/workspace/twitter-s-public-workspace/collection/9956214-784efcda-ed4c-4491-a4c0-a26470a67400?ctx=documentation).
#### Using OAuth 2.0 to generate a user access token
If you want to generate an OAuth 2.0 user access token in Postman you can generate OAuth 2.0 access tokens to use in conjunction with the X [API v2 Postman collection](https://www.postman.com/xapidevelopers/workspace/twitter-s-public-workspace/collection/9956214-784efcda-ed4c-4491-a4c0-a26470a67400?ctx=documentation).
If you click on the collection in your workspace and go to the tab entitled “Auth” and select the type to be “OAuth 2.0”. From there under the heading “Configure New Token” go to where it says “Configuration Options”. You can update the “Grant Type” to “Authorization Code (With PKCE)”.
You will want to update your Callback URL to match the callback url associated with your application. Additionally, you will want to update the following parameters:
* Auth URL - [https://x.com/i/oauth2/authorize](https://x.com/i/oauth2/authorize)
* Access Token URL - [https://api.x.com/2/oauth2/token](https://api.x.com/2/oauth2/token)
* Client ID - Your OAuth2.0 client ID from Dev Portal
* Client Secret - If you are using a confidential client
* Update Scope - Scopes to match the endpoints you want to connect to. Example “tweet.read users.read”
* Your callback URL (also known as the redirect URL). This must match what you have in your App's authentication settings.
* State - state
When you are ready can click “Get New Access Token” to generate an Access Token. If you see a dialog box that says something went wrong you may need to press the back button to login. You will need to authorize your app to have access to your account by clicking where it says “Authorize app” in the dialog box.
After you authorize your app you will be directed back to Postman where you can see your token and select the "Use Token" button to start making requests on behalf of an authorized user.
You are now ready to use the Postman collection.
## What's next
If you click on the button in Postman that says "Code", you can turn the request we just created into the language of your choosing such as Python, Node or Ruby to help you get started. Postman has [great documentation](https://learning.getpostman.com/) that might be helpful. We also have some [sample code on GitHub](https://github.com/xdevplatform) that can help you get integrated with the endpoints more quickly.
# Build for businesses
Source: https://docs.x.com/use-cases/build-for-business
Use X's powerful APIs to help your business listen, act, and discover.
## Listen to the conversation on x
Audience or API partners provide a list of hashed identifiers and X performs a match and produces segments that are made available against media buying on X. Partners can create these audiences with the [Audience API](/x-ads-api/audiences).
**How it works?**
**Web**
We offer a standard cookie matching process when working with MPP audience partners to identify segments to target against media buying on X. In addition, advertsiers can setup a [X Web Event Tag](/x-ads-api/measurement/web-conversions#web-event-tags) to collect website user data and create a corresponding Custom Audience.
**Setup Steps**
![]()
**How it works?**
**Mobile**
Please see [the Custom Audiences from Mobile Apps blog post](https://blog.x.com/2014/introducing-tailored-audiences-from-mobile-apps) for details.
**Flexible**
[Flexible audiences](/x-ads-api/audiences) give advertisers the ability to build and save audience combinations based on existing custom audiences or subsets of existing custom audiences. Subsets of a custom audience’s members can be targeted based on the recency and frequency of interaction.
**Restricted Use Cases for Custome Audiences**
[Read more about restrictions](https://developer.x.com/en/developer-terms/more-on-restricted-use-cases "Read more about restrictions")
### Audiences FAQ[](#real-time-tailored-audiences "Permalink to this headline")
**Q: We pushed a huge amount of data, why does the audience size show up as TOO\_SMALL?**
A: Currently the data is being added into audience in realtime, but the job which processes data to provide audience size will run only after a period of time. The correct audience size should be displayed in the UI after a matter of hours.
**Q: We finished sending audience data, and waited 24 hours or more, but still cannot target the audience - what should we do as next steps?**
A: Please confirm that the following things:
* The user ID being passed is correct and not malformed.
* The audience names being passed are correct and match previous membership updates.
* Please confirm the response from POST commands.
* Please confirm the ID Sync pixel is implemented correctly, and as described by ID Sync process enough users have visited the site in question to map users. Unmapped users in the membership updates will not be translated into targeted users.
If all else are confirmed as correct and working, please contact X product contacts with information as detailed as possible (see [Guide to Partner Inbounds](/x-ads-api/introduction) for example of preferred information).
**Q: How many times can we call the endpoint, and with what algorithm?**
A: We strongly recommend that you call our system with incremental deltas, and never re-send the complete audience memberships. The system has been tested to have a throughput sufficient to process incremental data updates for some of the largest websites in the world. The initial upload of audiences should be carefully throttled and first upload is expected to take a significant amount of time to complete.
**Q: What is the minimum size for an audience to be used for targeting?**
* The minimum size for an audience to is 100 users (post match). If an audience with less than 500 users is matched, it will not be available for targeting in the X Ads UI.
**Q: How long will it take to process the audience files? And how long will it take for the audience files to be ready in the X User Interface?**
* It typically takes 4-6 hours to process the audience files, but that will depend on the size of the file. Once the file is processed the audiences are available on the X Ads UI.
**Q: How is the match rate calculated?**
* Match Rate = 90 day active X users / number of users provided
**Q: How do we test if an audience file is working properly?**
* You can provide a test audience file and use “keltonlynn” as the advertiser handle. We can then verify that the file is able to be properly ingested and loaded into the X UI.
**Q: What is a partner user identifier (`p_user_id`)?**
* This is the identifier that is used by your company to uniquely identify each of your customers.
**Q: What is a standard ID?**
* This can be an email address, device ID, X @handle or ID).
**Q: How do I get the HMAC Key?**
* This will be provided by an encrypted email. Please provide your public PGP key to [mpp-inquiry@x.com](mailto:mpp-inquiry%x.com) and we will send you a test email to verify that everything is working. Once verified, we will send you the HMAC Key.
**Q: How do I verify that the hashing process worked using the given HMAC Key?**
* X will provide a test file (containing sample email addresses, device IDs, etc…) and a resulting hash file that you can verify your results against.
**Q: Is there a file size limitation for the full data match file?**
* No, there is no size limitation for the full data match file.
**Q: How long will it take for the full data match file to be processed?**
* Once the file is received by X, it will take approximately 1 day to process the file.
### CRM
This document describes the integration details for Custom Audiences CRM partners including file formats & data exchange process.
**Summary**
Company will provide a list of hashed common user identifiers (i.e. e-mail addresses) or partner user IDs on behalf of a customer to X to perform a blind match and produce a list of X User IDs for targeting. The segments for targeting will be made available to the advertiser’s specific @handle specified by the filename in ads.x.com campaign setup.
All files from Company will be provided to X through a secure package on IronBox ([www.golockbox.com](http://www.golockbox.com)) through a specific account granted to Company by X. X will provide access to IronBox. Documentation on IronBox APIs can be found at [https://secure.goironcloud.com/Docs/Help/](https://secure.goironcloud.com/Docs/Help/).
#### Partner ID Matching Requirements
If company uses its own standard ID system to track users (i.e. not common user identifiers like email addresses, device ids, X user ID, etc...) then this is the recommended process.
**1. Full Data match**
Initially, Company will provide a comprehensive list of all user records which include a unique common user identifier with X in a single file to perform a full data match and produce a mapping stored by X of Partner IDs (`p_user_id`) to X IDs (`tw_id`). This will be done on a 2-3 month basis regularly to ensure proper upkeep. Once the match is completed, X will share a baseline match rate from this file with Company via e-mail.
The format of this file should be:
Name Convention: FullDataMatch.\[CompanyName].txt
Hashing Algorithm: HMAC\_SHA-256
Format:
Column 1: HMAC hashed value of common identifiers
Column 2: Partner User ID (unique per user, non-unique in file)
Column Delimiter (CSV): Commas will be used to delimit the hashed common user identifier from the Partner ID
Line separated values
* Ex: If user record A has Partner User ID 1 and common identifier 1, 2 and 3:
| | |
| :----------------------- | :--------- |
| common user identifier 1 | p\_user\_1 |
| common user identifier 2 | p\_user\_1 |
| common user identifier 3 | p\_user\_1 |
\*See Hashing Directions section for common user identifiers below
**2. Custom Segment Lists**
Company will provide lists of users in the form of `p_user_id` to create custom audiences for customers for targeting on X.
* Line separated values
* `p_user_id`
* * (Same as provided in 1. Full Data Match section above. If the value provided in full data match is hashed then Company will provide same hashed value in audience file. If value provided is not hashed then Company will provide unhashed value.)
#### Standard Matching Requirements
If company does not use a standard ID for mapping of all customer user identifiers, this is the recommended process.
**Custom Segment Lists**
Company will provide lists of hashed common user identifiers directly to X on behalf of customers to to create custom audiences.
The format of this file should be:
* Line separated values
* Hashed common user identifier (i.e. e-mail address)
* Follow file naming conventions outlined below
* Follow hashing directions for e-mail addresses below (in Hashing Directions)
#### Custom Segment List File Naming & Operations
The operation of a file will be dictated by the name of the file with the following available operations and general file naming convention: audiencename\_partnername.handle.operation.filetype
* audiencename: The name of the Custom Audience. This field is the name that will be displayed when selecting the audience in the ads.x.com campaign setup UI e.g. brand\_loyalty\_card\_holders.
* partnername: Name of the company delivering the data on behalf of advertiser e.g. company\_name.
* handle: X Account (@handle) that will have access to Custom Audiences e.g. @pepsi, @dietpepsi
* operation: new, add, remove, removeall, replace (details below)
* : Standard Unix epoch time in seconds, used to ensure that each audience file uploaded is unique
* filetype: file should be in \*.txt format
#### Creating and Updating Audiences
Create a new audience with a single file e.g. loyalty\_card\_holders\_partnername.pepsi.new\.txt
Add - Add the matches from a list to an existing audience e.g. loyalty\_card\_holders\_partnername.pepsi.add..txt
Remove - Remove the matches from a list from an existing audience Ex: loyalty\_card\_holders\_partnername.pepsi.remove..txt
Remove All - Remove the matches produced from a regularly updated cumulative list from all audiences for that client (i.e. Client’s Opt Out List). Ex: partnername.pepsi.removeall.txt
* This can be used for a comprehensive list of users who have opted-out from the Advertiser.
* X will only respect the latest list provided in this file, and will respect across all existing and future audiences for matched.
X users at the time this file was provided & processed.
Replace - Remove an existing audience and replace it with a new audience list. Ex: loyalty\_card\_holders\_partnername.pepsi.replace..txt
Overall Company Opt-Out - Company will provide a cumulative Opt-Out file to remove users that have opted out as per the Company’s Opt-Out policy.
X will only respect the latest list provided in this Company Opt-Out file and will respect across all existing and future audiences for matched X users at the time this file was provided & processed. The format of the Company Opt-Out file will be as follows: Ex: partnername.removeall.txt
Delete - Remove an existing audience from the current list of audiences e.g. Ex: loyalty\_card\_holders\_partnername.pepsi.delete.txt
#### Hashing Directions
X will securely share a base64 encoded production key via PGP for hashing common user identifiers (i.e. email addresses). Company will base64 decode the key to produce a 32-byte key to be used to perform the hashing.
Example base64 encoded key:
BrQvOg+dACBUmKjRiNxZgJLh6zydjS0ZOv80FelTNzM=
Example Base64 decoded key:
/:� TшY
Normalization: Company will perform basic normalization on the common user identifiers before hashing (except on Device IDs, see Device ID Normalization section).
#### E-mail Normalization
Namely, strip out the leading and trailing spaces and also lowercase the email address.
Ex: Raw e-mail address: testemail\_Organisational\_baseball+884`@`It92I6Ev2B`.`Com
After normalization: testemail\_organisational\_baseball+884`@`it92i6ev2b`.`com
Hashed value: 74d9584eded0ad1e5572a1c1849f3716751d371d6117a6155dad5363f4b4fbec
Note: The specific number of characters for both the encoded hmac and key could vary based on the input and the encoding so the specific number of characters.
#### Device ID Normalization
We will have the same requirements for hashing of device IDs using a SHA-256 hashing algorithm and a common salt that we provide to data partners. We strip out spaces like we do with email addresses, but there is no lowercase normalization for IDFAs/Android IDs and the exact format of the IDFA/Android ID should be used.
Here is example raw format of Device IDs for iOS & Android, pre-hashing:
iOS IDFA: DD99CFF7-6186-4602-9DF2-ED3FD0B2D431
Android ID: b5bf2122961b3595
Hashed iOS IDFA: 134fb8cd95c7fd42e2793f469a447198ca5f990968db2dbadad70e723ed9750b
Hashed Android ID: 130dddff1939f229476f50bc8adab8fcb7e3525b0e9604fe8effc15e68cee4a4
#### X User ID Normalization
X IDs will still be hashed as the grouping of data - ie Customer List of @handles - is private to the advertiser even though it is not PII. We will have the same requirements for hashing of X IDs using a SHA-256 hashing algorithm and a common salt that we provide to data partners. Spaces should be stripped out of both the X ID/`@`username, but User IDs do not require normalization. @usernames should be lowercased for normalization. And the @ symbol should not be included as part of the username.
The raw ID format will be:
* User ID: 27674040
* @username: testusername
Hashed User ID: bf6b57d4e861e83bea8bbed2b800b251a64c95468ee6e8cb07c3368c9ed45e85
Hashed @username: 12201ae78ad1afa907c7112d17f498154ffb0bf9ea523f5390e072a06d7d9812
### ID Sync Integration
Partners sending data with a `p_id` must undergo an ID Sync process to generate a mapping of the advertiser or partner’s user ids to X user ids. This allows advertisers to directly target their own user segments on X. Partners must also set the value of the param `user_identifier_type` to either `TALIST_PARTNER_USER_ID` or `TAWEB_PARTNER_USER_ID` while sending their membership updates.
* **Web Only**: This can be done by placing a pixel on the advertiser’s site, as outlined below.
* **List**: This can be done using any of the methods described on the [CRM](/x-ads-api/audiences#crm) page.
#### Pixel URL
| |
| :----------------------------------------------------------------- |
| **Base URL** |
| [https://analytics.x.com/i/adsct](https://analytics.x.com/i/adsct) |
#### Pixel Parameters
| | |
| :------------ | :---------------------------------- |
| **Parameter** | **Description** |
| `p_id` | Your X-assigned partner id |
| `p_user_id` | The user’s id in the partner system |
#### ID Sync Pixel:
Using an example partner id of 111, and an example `p_user_id` of abc, the constructed pixel would be the following:
```json
```
**Opt-Out File Configuration and Sending Opt-Out Files**
Partners should provide X with a list of users that to the partner’s best knowledge have selected to opt-out of targeted ad delivery. The format of file should be sent as:
| | | | |
| :---------------- | :---------------------------------- | :-------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Column Number** | **Column Name** | **Column Type** | **Description** |
| 1 | Partner ID | string | The “partner id” is the ID that X provides to the Partner in order to uniquely identify each Partner. |
| 2 | The user’s id in the partner system | string | The `p_user_id` is the unique ID that is used to identify the user by the Partner. The file containing these opt-out users should be uploaded using the [TON upload](/x-ads-api/audiences) endpoint and the path of uploaded data should be sent to the Global Opt Out endpoint here:[PUT accounts/:account\_id/custom\_audiences/global\_opt\_out](/x-ads-api/audiences). |
**Sending Membership Updates**
As specified in our endpoint documentation, when passing users via the [POST custom\_audience\_memberships](/x-ads-api/audiences) endpoint you should pass a customer ID to enable a cookie based match. Partners sending data with a `p_id` **must** set the `user_identifier_type` to `TALIST_PARTNER_USER_ID` or `TAWEB_PARTNER_USER_ID`.
All other steps will remain the same as those listed in the [Real-Time Audience API Integration Guide](/x-ads-api/audiences)
### Custom Audiences User Data
This document outlines the format for \[Custom Audience]/x-ads-api/audiences user data.
**Data normalization**
**Device IDs**:
* IDFA - lower-cased with dashes; ex: `4b61639e-47cc-4056-a16a-c8217e029462`
* AdID - original format on device is required, not capitalized with dashes; ex: `2f5f5391-3e45-4d02-b645-4575a08f86e`
* Android id - original format on device is required, not capitalized without dashes or spaces; ex: `af3802a465767e36`
**Email Addresses**:
* lowercase, remove leading and trailing spaces; ex: `support@x.com`
**X Usernames**:
* no @, lowercased and leading and trailing spaces trimmed; ex: `jack`
**X User IDs**:
* Standard integer; ex: `143567`
**Data hashing**
The data for each line must be hashed using `SHA256`, without a salt. Additionally, the final output hash must be in lower case. E.g., 49e0be2aeccfb51a8dee4c945c8a70a9ac500cf6f5cb08112575f74db9b1470d and \*\*not \*\*49E0BE2AECCFB51A8DEE4C945C8A70A9AC500CF6F5CB08112575F74DB9B1470D
```
# hasing user @AdsAPI using python
import hashlib
hashlib.sha256("adsapi".encode()).hexdigest()
#output
49e0be2aeccfb51a8dee4c945c8a70a9ac500cf6f5cb08112575f74db9b1470d
```
Additional code samples for hashing can be found at [github.com/xdevplatform/ads-platform-tools](https://github.com/xdevplatform/ads-platform-tools).
### Custom Audiences: Web
**Information**
Partners will send a list of IDs (`p_user_ids`) to target on behalf of an advertiser. This is accomplished through an ID Sync process that builds a mapping between the `p_user_ids` and X user ID. This mapping is then used to produce lists of X User IDs that can be used for Targeting. These custom audiences will be made available on the advertiser’s specific @handle specified by the label on ads.x.com Custom Audiences Web campaign setup.
X will provide the secure pixel that can be dropped on partner tags and sites in order to match the IDs (`p_user_ids`) to X user IDs. Once the ID Sync process is complete, the targeting files will be created by the partner and will be made available to X through a HTTPS endpoint. These targeting files are ingested on a regular basis by X and are then made available in the X UI.
**X Secure Pixel**
The X secure pixel will look as follows:
[https://analytics.x.com/i/adsct?p\\\_user\\\_id=xyz\&p\_id=123](https://analytics.x.com/i/adsct?p\\_user\\_id=xyz\&p_id=123)
**`p_user_id`** - xyz represents the partner user ID that is provided by the Partner
**`p_id`** - 123 represents the unique ID for the Partner (provided by X)
**Partner HTTPS Endpoint & Targeting User File**
Partner will need to provide X with a HTTPS endpoint and credentials (username/password) that can be used to ingest the targeting file on a regular basis. A sample HTTPS endpoint will look as follows:
```
https://