Running Graph Queries

Run a graph query via API

Request

Run a graph query by creating a POST request to the graph queries resource. You will need to specify a graph query template and the parameters it needs:

1
API_KEY=YOUR_API_KEY_HERE
2
curl -X POST -H 'Content-Type: application/json' \
3
    -H "Authorization: Bearer $API_KEY" -d'{
4
  "data": {
5
    "attributes": {
6
      "graph-query-template-id": YOUR_TEMPLATE_ID,
7
      "parameter-map": {
8
        "example-key": "example-value",
9
        "...": "...
10
      }
11
    }
12
  }
13
}' https://api.withpersona.com/api/v1/graph-queries

In parameter-map, include each parameter defined in your graph query template and the value you want to pass in. For example, if your graph query template contains a parameter called account-id, your parameter-map may look like this:

{
  "account-id": "act_UqdkF248jR4yH8xxixsMhKnt"
}

Response

The HTTP response includes a graph query ID that you can use to poll for the query result:

1
{
2
  "data": {
3
    "type": "graph-query",
4
    "id": "grphq_yourfirstqueryid",
5
    "attributes": {
6
       "params": {
7
         <Your query params>
8
       },
9
       "created-at": DATE_TIME_STRING,
10
       "completed-at": null,
11
       "status": "submitted",
12
	   ...
13
    }
14
  }
15
}

Get graph query results via API

Request

Fetch the results of a graph query using the graph query ID:

1
API_KEY=YOUR_API_KEY_HERE
2
curl -X GET -H 'Content-Type: application/json' \
3
    -H "Authorization: Bearer $API_KEY" \
4
  https://api.withpersona.com/api/v1/graph-queries/GRAPH_QUERY_ID

Each new graph query’s status starts as submitted.

Once the status is completed, the results are available in the response.

Response

A completed graph query contains the following fields:

1
{
2
  "data": {
3
    "type: "graph-query",
4
    "id": "grphq_yourfirstqueryid",
5
    "attributes": {
6
       "status": "completed",
7
       "params": {
8
         <Your query params>
9
       },
10
       "created-at": DATE_TIME_STRING,
11
       "updated-at": DATE_TIME_STRING,
12
       "errored-at": DATE_TIME_STRING,
13
       "completed-at": DATE_TIME_STRING,
14
       "stats": {
15
         num-accounts: 5,
16
         num-device-fingerprints: 2,
17
         ...
18
       },
19
       "explorer-url": LINK_TO_VISUALIZE_QUERY_IN_PERSONA_DASHBOARD,
20
       "node-limit-reached": false,
21
  		 "nodes": [
22
         {
23
           "type": "account",
24
           "value": "act_123example"
25
         },
26
         {
27
           "type": "device_fingerprint",
28
           "value": "123example"
29
         },
30
         ...
31
       ]
32
    }
33
  }
34
}

If your team would like to get additional data in the API response, please let your Persona Account Team contact know.

About node limits

Every graph query requires processing huge amounts of data and analyzing the relationships between many data nodes. To ensure performant queries, the computation will not continue traversing more nodes once it hits the graph query’s specified node limit.

When a graph computation hits the node limit, it will return the results it has accumulated so far. Thus, if node-limit-reached is true, the results may only reflect the portion of the possible results.

If you would like to get paginated results, please reach out to your Persona Graph contact.

Best practices

For optimal query performance, try to keep the range of nodes being queried over small. For example:

• In general, a query over a smaller created-at time range will be faster.
• In general, a query on a more unique node type, such as government ID number, will compute faster than a query on a node type with lots of matches, such as name.