You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: x-ads-api/fundamentals/accessing-ads-accounts.mdx
+3-3Lines changed: 3 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -12,7 +12,7 @@ There are two different types of accounts involved in using the Ads API: advert
12
12
* Advertising accounts are registered on **business.x.com** and identified in the API by account\_id. Advertising accounts link directly to funding sources and leverage content from one or more X user accounts as ‘promotable users’. Each advertising account can grant permission to one or more X user accounts. The advertising account, or “current account,” is represented in nearly every URL executed as an in-line :account\_id parameter.
13
13
* X user accounts (such as @AdsAPI) are identified by user_id in the Ads API. One or more of these accounts can be associated with an advertising account. The authenticated X user account making requests on the API is referred to as the ‘current user.’ A listing of advertising accounts that the current user has access to can be found with [GET accounts](/x-ads-api/campaign-management/reference#accounts). ‘Promotable users’ are X handles that can be promoted by a specific advertising account. For more details about this, see [Obtaining Ads Account Access](/x-ads-api/introduction).
14
14
15
-
## Methods for Ad account access
15
+
## Methods for ad account access
16
16
17
17
There are two methods you can use to make Ads API requests for an advertiser’s account:
18
18
@@ -36,7 +36,7 @@ Each user will have a level of access as requested upon [application to the Ads
36
36
37
37
**Note:** Ads API developers who requested access prior to July 2023 may have different levels of access and permissions, and may be limited to five OAuth tokens. See our guide on [increasing access](/x-ads-api/getting-started/increasing-access) to access to additional endpoints or lift token limits for existing applications.
38
38
39
-
### Ad Account-level permissions
39
+
### Ad account-level permissions
40
40
41
41
Each user that has access to an Ads Account will have a specific account-level permission: **Account administrator**, **Ad manager**, **Campaign analyst**, **Organic analyst**, and **Creative Manager**; see **business.x.com** for the latest documentation for account-level permissions. Applications should retrieve the permissions for the currently authenticated user via the [Authenticated User Access](/x-ads-api/campaign-management/reference#authenticated-user-access) API endpoint to determine which API endpoints and Ads features they can access.
42
42
@@ -75,7 +75,7 @@ To gain access to create Promoted-Only Posts on behalf of the `FULL` promotable
75
75
**Note:** See **[Obtain your (Developer) access token](/x-ads-api/fundamentals/accessing-ads-accounts#2-obtain-your-developer-access-token)** section above for details.
76
76
</Note>
77
77
78
-
## Sample Use-Case
78
+
## Sample use case
79
79
80
80
### Advertiser's access token via OAuth 3-legged web flow
Copy file name to clipboardExpand all lines: x-ads-api/fundamentals/error-codes-and-responses.mdx
+2-2Lines changed: 2 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,7 +4,7 @@ keywords: ["Ads API errors", "error codes", "Ads API error handling", "error res
4
4
5
5
description: Successful responses are indicated with a 200-series HTTP code and a JSON-based payload containing the object(s) requested, created, modified, or delete...
6
6
---
7
-
## Typical Response Structure
7
+
## Typical response structure
8
8
9
9
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.
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.
28
28
29
-
## Error Response Structure
29
+
## Error response structure
30
30
31
31
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 an HTTP 404 along with an HTML response. In this case, it’s safe to assume that the content cannot be found (HTTP 404 means “Not Found”).
Copy file name to clipboardExpand all lines: x-ads-api/fundamentals/making-authenticated-requests.mdx
+2-2Lines changed: 2 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -48,7 +48,7 @@ Most resource URLs feature one or more in-line parameter. Many URLs also take ex
48
48
49
49
In-line parameters are denoted with a pre-pended colon (”:”) in the **Resource Path** section of each resource. For example, if the account you were working on were identified as `"abc1"` and you were [retrieving the campaigns associated with an account](/x-ads-api/campaign-management/reference#campaigns), you would access that list by using the URL `https://ads-api.x.com/6/accounts/abc1/campaigns`. By specifying the in-line `account_id` parameter described in the resource URL (`https://ads-api.x.com/6/accounts/:account_id/campaigns`), you’ve scoped the request to objects associated only with that account.
50
50
51
-
## Using Access Tokens
51
+
## Using access tokens
52
52
53
53
The X Ads API uses signed HTTPS requests to validate an application’s identity and also obtain the permissions granted to the end-user that the application is making API request on behalf of, represented by the user's access token. All HTTP calls to the Ads API must include an Authorization request header (using OAuth 1.0a) over the HTTPS protocol.
54
54
@@ -116,7 +116,7 @@ After getting familiar with making requests to the Ads API using Twurl, it is ti
116
116
Here are some examples using C#, PHP, Ruby, and Python - [code samples](/resources/fundamentals/authentication#oauth-1-0a-2).
117
117
118
118
119
-
## Custom Implementation
119
+
## Custom implementation
120
120
121
121
There are some scenarios that require implementing OAuth 1.0a authentication without the support of an open-source library. [Authorizing a request](/resources/fundamentals/authentication#authorizing-a-request) provides detailed instructions for implementing support for creating the Authorization header. We strongly recommend using a community-supported library.
Copy file name to clipboardExpand all lines: x-ads-api/fundamentals/pagination.mdx
+2-2Lines changed: 2 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -7,7 +7,7 @@ description: In order to support a larger maximum number of campaigns and effici
7
7
8
8
In order to support a larger maximum number of campaigns and efficient retrieval of all entities associated with an account, the Advertiser API now supports pagination on many GET endpoints. The paging mechanism is easy to use and very similar to the REST API’s cursor-based pagination as described in [Using cursors to navigate collections](https://developer.x.com/en/docs/x-api/v1/pagination).
9
9
10
-
## Getting Started
10
+
## Getting started
11
11
12
12
For designated GET requests, we now accept `cursor` and `count` query parameters, which are both optional. If a response has more than `count` entities, these endpoints will now return the first `count` entities and a `next_cursor` key in the response JSON.
13
13
@@ -32,7 +32,7 @@ To get the next series of responses, you would add `cursor` to your query params
32
32
"request": {...}
33
33
}
34
34
```
35
-
## Going Deeper
35
+
## Going deeper
36
36
37
37
For most endpoints, the maximum `count` value is **1,000**, the minimum is **1**, and the default is **200**.
Copy file name to clipboardExpand all lines: x-ads-api/fundamentals/rate-limiting.mdx
+6-6Lines changed: 6 additions & 6 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -7,7 +7,7 @@ description: "The Advertiser API is rate limited similarly to REST API v1.1, as
7
7
8
8
The Advertiser API is rate limited similarly to REST API v1.1, as documented here: [REST API Rate Limiting in v1.1](https://developer.x.com/content/developer-twitter/en/docs/basics/rate-limits). Unlike REST API v1.1, there is no programmatic index of the limits per endpoint. The endpoint rate limits and reset windows are communicated via HTTP response headers. All rate limiting in the Ads API utilizes OAuth 1.0A.
9
9
10
-
## User Level and Ad Account Level Limits
10
+
## User level and ad account level limits
11
11
12
12
There are two types of rate limits: user token level and ad account level. A subset of endpoints are enabled to use ad account level rate limiting. A user token is the [OAuth access token](/resources/fundamentals/authentication#obtaining-access-tokens-using-3-legged-oauth-flow) you use to authenticate and call the Ads API. Each user token can have access to one or more ad accounts.
13
13
@@ -21,15 +21,15 @@ The ad account level rate limits are provided only for GET endpoints to enable a
21
21
22
22
For ad account level rate limited endpoints, the user level rate limit is set at a high value representing a global quota for your entire application. When available the ad account level rate limit should take precedence in controlling your request volume.
23
23
24
-
## Best Practices
24
+
## Best practices
25
25
26
26
1) Save a timestamp in your database with the last synced timestamp, and when requesting data where applicable request data with `sort_by=updated_at-desc` option to enable you to stop your syncing process after reaching data older than your last synced timestamp. This will avoid syncing the same data redundantly.
27
27
28
28
2) Request multiple entities in a single request: Some endpoints allow you to specify a comma-separated list of values, to retrieve multiple pieces of similar data. This can reduce the overall number of calls you make and thus leverage rate limit more efficiently.
29
29
30
30
3) Request maximum “count” in your requests: Some endpoints such as [GET accounts/:account\_id/targeting\_criteria](/x-ads-api/campaign-management/reference#targeting-criteria) are strongly recommended to call with maximum count value to return 1000 objects instead of the default of 200.
31
31
32
-
## Analytics Syncing
32
+
## Analytics syncing
33
33
34
34
See the [Analytics Rate Limiting Guide](/x-ads-api/analytics#best-practices) for more information about analytics endpoint rate limits.
35
35
@@ -39,16 +39,16 @@ _Is it possible to increase rate limits for a particular ad account or our appli
39
39
40
40
We generally cannot raise rate limits and they are set to support the largest of ad accounts. Please implement the Best Practices listed in this document as a first step, and if rate limits are still impacting your ability to scale or achieve business objectives please reach out to your X Ads API contacts with complete details about the use case and requests involved.
41
41
42
-
## Scopes of Rate Limiting
42
+
## Scopes of rate limiting
43
43
44
44
### Scopes for this doc
45
45
46
46
* Category: all endpoints that fall into the given category are rate limited from a single allocated limit per window.
47
47
* Endpoint: each endpoint has its own distinct allocated limit per window.
48
48
49
-
## Ads API Rate Limit Chart
49
+
## Ads API rate limit chart
50
50
51
-
### Ads API Rate Limits
51
+
### Ads API rate limits
52
52
53
53
| Endpoint Type | Scope by Endpoint or Category | Rate Limit per 1-minute window |
0 commit comments