Overview

Brief Overview of the GraphQL APIV2

The GraphQL API for Pulsar uses a schema to define relationships between the data on the platform, allowing you to filter and organize the data you pull from the platform, as well as clearly define the relationships of the data you choose to upload to the platform.

Data Limitations

The API will be rate limited to 5 requests every 1 second

Data from the Pulsar API is always delivered in JSON format.

The maximum results per page is 100, and a next token is available for paginated results.

Twitter

In accordance with our contract with Twitter, we are not able to use the API to provide any of the following pieces of information:

• User Bio (the full bio of a user)

• User Follower Count (total number of followers a user has)

• User Coordinates (geolocated coordinates of a user)

• Post Coordinate (geolocated coordinates of a post)

Keeping this in mind, this data is still accessible on platform, and you can still filter on user bio keywords when pulling posts using the API.

How to Use the GraphQL API

The first step is to talk to your account manager! They can help you get an API key as a demo or as part of your license, so that you and your team can begin testing the API. The API key is unique to each user’s access, so if you are on multiple subdomains on Pulsar, you will need a unique key for each subdomain you have access to. Note that if you already have an API key for the REST API, this is the same key you will use for the GraphQL API.

What Does a Query Look Like?

A GraphQL query has two parts: the call, and the query variables.

The call (displayed on the first tab below) first gets a defined name, and the arguments (variables) being passed in to the types within the query.

Then in here, using the schema, you define the fields you want as a part of that call.

Each field has its own special schema that provides a list of subfields and variables needed to specify what should be returned.

query Searches($sortBy: AllowedFieldsForSorting, $status: [SearchStatusEnum!]){
  searches(sortBy:$sortBy, status:$status){
    totalCount
    nodes {
        name
	startDate
	status
	totalContents
    }
  }
}

The query variables are used to fill in the parameters as seen above.

These are also defined using the schema, but the formatting style for this data is called JSON.

{
  "sortBy": "VELOCITY_DAY",
  "status": [
    "READY"
  ]
}

What Does A Payload Look Like?

A returned payload can vary based on the call sent, but you will be sent back some form of a JSON with your data organized precisely how you have asked for it back.

For example, in a Brand query on CORE like this:

query Brands($page: Int, $limit: Int) {
  brands(page: $page, limit: $limit){
    total
    nextPage
    brands {
      brandType
      brandsetName
      profiles{
        id
        name
      }
      id
    }
    }
}

You will see a return that looks like this:

{
  "data": {
    "brands": {
      "total": 106,
      "nextPage": 2,
      "brands": [
        {
          "brandType": "competitor",
          "brandsetName": "Extendi",
          "profiles": [
            {
              "id": 1,
              "name": "UNILAD"
            },
            {
              "id": 4,
              "name": "DEV Community 👩💻👨💻"
            }
          ],
          "id": 1
        },
        {
          "brandType": "owned",
          "brandsetName": "Extendi",
          "profiles": [
            {
              "id": 381,
              "name": "Schiaccia Il 5"
            },
            {
              "id": 382,
              "name": "edoardomarsili"
            },
            {
              "id": 383,
              "name": "Schiaccia Il 5"
            },
            {
              "id": 523,
              "name": "Edoardo Marsili"
            }
          ],
          "id": 186
        }
      ]
    }
  },
  "variables": null
}

Note that the formatting is the same as the variables for a query: JSON.

What’s particularly nice about this is you know exactly where to find each bit of a query you have requested, as it is always in the same order that you requested it.

At the end of your payload will be the variables you used to define the query, so you always have that information handy in the return if you need to sense check your data.

What do I Do Now?

The next step is to find a testing environment. We hope to have an in-doc graph explorer available in the future where you can input your key and run sample calls for the GraphQL API. For now, we recommend a program like Insomnia for testing GraphQL API calls. This will allow you to see the schema dynamically while working on tests! The schema is incredibly important because it helps you understand all of the fields, subfields, and return types you can add to your call.

For GraphQL API access, make sure you:

• Use the following subdomain exactly as the domain you're querying for TRAC (receiving TRAC metadata):https://trac.pulsarplatform.com/graphql

• Use the following subdomain exactly as the domain you're querying for TRAC (receiving TRAC data):https://data.pulsarplatform.com/graphql/trac

• Use the following subdomain exactly as the domain you're querying for CORE:https://data.pulsarplatform.com/graphql/core

• Use the following subdomain exactly as the domain for using the Pusher API:https://interaction-pusher.pulsarplatform.com/graphql

• Remember to specify Authorization Bearer= "your token here" in your header. In Insomnia, there is a menu for selecting authorization method. Selecting Bearer and inputting your token in the first field should grant you access to the schema

• Your API method must be POST whether you are using the pusher or data explorer. You specify in the body whether you are performing a query (for the data explorer) or a mutation (for the pusher)