API Limitations

Tapjoy's GraphQL API has certain protections in place to prevent excessive or abusive API calls. If your integration is exceeding the limits in place, please contact your Tapjoy AM or support to understand how your integration can be optimized or how to increase your limits.

The examples below are demonstrated in the context of an Advertiser, but would apply to Publisher integrations as well.

Pagination

When querying for a paginated type, clients must:

Supply a first or last argument
Not exceed 100 nodes in a single page

If the maximum value has been exceeded, then the results will be truncated and, as a result, the requested first / last argument will be ignored.

For example:

{
  advertiser {
    adSets(first: 50) {
      edges {
        node {
          id
          name

          ads(first: 50) {
            edges {
              node {
                id
                name
              }
            }
          }
        }
      }
    }
  }
}

In the above query, this will return a maximum of 50 ad sets, each with a maximum of 50 ads.

In order to paginate through collections, you must provide an after or before argument to control where to start the page. For example:

{
  advertiser {
    adSets(first: 50, after: "Mg==") {
      edges {
        node {
          id
          name
        }
      }

      pageInfo {
        endCursor
        hasNextPage
      }
    }
  }
}

In the above query, this will return a maximum of 50 ad sets, starting at the cursor position "Mg==". That position is determined based on the endCursor returned from a previous query. Pagination should be considered complete when hasNextPage is false.

You can read more about pagination on the official GraphQL website.

Call complexity

To pass schema validation, all GraphQL API calls must not exceed more than 10,000 "calls". In this case, a "call" refers to a request for a resource. Since GraphQL allows multiple calls to be combined into a single query, the total number of calls for a single query is calculated ahead of time by the API before the query gets executed.

The number of calls is roughly equivalent to the number of resources being selected from the result (e.g. campaigns, ad sets, ads, apps, insights, etc.)

Let's consider the same example from above:

{
  advertiser {
    adSets(first: 50) {     # <= 50 calls
      edges {
        node {
          id
          name

          ads(first: 50) {  # <= 50 calls
            edges {
              node {
                id
                name
              }
            }
          }
        }
      }
    }
  }
}

In this example, the client is asking for up to 50 ad sets at a time; for each ad set, they are asking for up to 50 ads from the ad set.

To calculate the total number of calls:

50      = 50 ad sets
+
50 x 50 = 2500 ads
        = 2550 calls

At the current time, there is no rate limit for number of calls per hour. However, this will likely change in the future.

Insights complexity

Reporting insights being queried at any level incur an additional complexity cost not reflected in the basic calculation above. An additional 1 call is added to the calculation for each day being queried.

Let's consider an example:

{
  advertiser {
    # 50 calls
    adSets(first: 50) {
      edges {
        node {
          id
          name

          # 7 calls
          insights(timeRange: {from: "2018-03-01T00:00:00Z", until: "2018-03-08T00:00:00Z"}) {
            timestamps
            reports {
              country
              impressions
              conversions
              spend
            }
          }
        }
      }
    }
  }
}

In this example, the client is asking for up to 50 ad sets at a time; for each ad set, they are asking for 7 days worth of reporting data across 3 metrics and 1 segment.

To calculate the total number of calls:

50      = 50 ad sets
+
50 x 7  = 350 insights
        = 400 calls

Data retention

The Tapjoy GraphQL API can access the last two years of data.