Skip to main content
API docs by Redocly

InfoSum Developer Documentation (1.0)

Download OpenAPI specification:Download

InfoSum Support: support@infosum.com Terms of Service

This page contains the documentation for the InfoSum Developer API. The methods allow you to try making requests and inspect the input and output formats.

Official documentation

Tyrael

Activations

List Activations

List current activations, subject to the optional request filters.

Authorizations:
API_Keys
query Parameters
filter.campaign_name
string

Campaign Name

The filter to be applied to the campaign name. Case insensitive. Supports partial names.

filter.submitted_at_filter.start_time
string <date-time>

Start

Defines the earliest time the filter is applied from. The filter matches all dates after this point in time, inclusive.

filter.submitted_at_filter.end_time
string <date-time>

End

Defines the time the filter is applied until. The filter matches all dates before this point in time, inclusive.

filter.query_successful
boolean

Query Successful

Filters activations that were successfully completed or not.

filter.results_expired
boolean

Results Expired

Filters activations that have expired or not.

filter.push_destinations
Array of strings

Push Destinations

Filters queries that have been pushed to the specified destinations.

filter.output_columns
Array of strings

Output Columns

Filters activations by the selected output columns. Activations which contain any of the specified output columns are included in the result

filter.activation_dataset_private_ids
Array of strings

Activation Dataset Private IDs

Filters queries by the activation dataset private ID used in the query. Activations for any of the dataset private IDs specified are included in the result.

filter.project_ids
Array of strings

Project IDs

Filters queries by the projects that the activation dataset belongs to. Activations whose dataset belongs to any of the specified projects are included in the result.

sort.by
string

By is the field to sort by.

sort.order
string
Default: "ASCENDING"
Enum: "ASCENDING" "DESCENDING"

Order is the order to sort in. Defaults to ascending.

  • ASCENDING: Sort in ascending order.
  • DESCENDING: Sort in descending order.

Responses

Response samples

Content type
application/json
{
  • "activations": [
    ]
}

Queue an Activation

Create an Activation and queue the query for execution. Returns immediately with an ID of the Activation created. Use the Get Activation endpoint to see if the query has run. Only available for use with Activation Datasets.

Authorizations:
API_Keys
Request Body schema: application/json
required

Used to queue an Activation Query with the CreateActivationQuery endpoint.

query
string (Query)

The Query that should be executed. This takes the format of an InfoSum Activation Query. See the documentation of the InfoSum Activation Query Language for more information.

Array of objects (Path Overrides)

A list of instructions on how to connect two datasets, overriding the automatic choices made by the core engine.

campaign_name
string (CampaignName)

A name that a user can associate with an activation query.

column_separator
string (Column Separator)

The separator to be used to delimit activation data columns.

object (tyraelActivationStringLiteral)

ActivationStringLiteral contains information about a string literal activation column.

object (HeaderOverrides)

An optional map of query output column to header override.

Array of objects (StringLiteralColumns)

The optional list of string literal columns.

multi_value_delimiter
string (MultiValueDelimiter)

The delimiter for multi-value columns.

identities_to_flatten
Array of strings (IdentitiesToFlatten)

A list of multi-value identity columns to be flattened.

Responses

Request samples

Content type
application/json
{
  • "query": "string",
  • "path_overrides": [
    ],
  • "campaign_name": "string",
  • "column_separator": "string",
  • "string_literal_column": {
    },
  • "header_overrides": {
    },
  • "string_literal_columns": [
    ],
  • "multi_value_delimiter": "string",
  • "identities_to_flatten": [
    ]
}

Response samples

Content type
application/json
{
  • "activation_id": "string",
  • "query_completed": true,
  • "query_error": {
    },
  • "query_response": {
    }
}

Validates an Activation Query

Performs validation of an Activation Query without executing it.

Authorizations:
API_Keys
Request Body schema: application/json
required

ValidateActivationQueryRequest is the output of the ValidateActivationQuery endpoint.

query
string (Query)

The query to be validated. This takes the format of an IQL Query. See the documentation of the IQL for more information.

Array of objects (Path Overrides)

A list of instructions on how to connect two datasets, overriding the automatic choices made by the core engine.

object (tyraelActivationStringLiteral)

ActivationStringLiteral contains information about a string literal activation column.

object

HeaderOverrides is an optional map of query output column to header override.

Array of objects (String Literal Columns)

The list of optional string literal output columns for the query

Responses

Request samples

Content type
application/json
{
  • "query": "string",
  • "path_overrides": [
    ],
  • "string_literal_column": {
    },
  • "header_overrides": {
    },
  • "string_literal_columns": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true
}

Get an Activation

Get detailed information about an Activation, including query and push statuses.

Authorizations:
API_Keys
path Parameters
activation_id
required
string

Activation ID

The unique ID of the activation to get.

Responses

Response samples

Content type
application/json
{
  • "activation": {
    }
}

Connections

List all available Connections

List all Connections available from user owned Datasets to Datasets which the user has been granted access.

Authorizations:
API_Keys
query Parameters
filter.origin_private_ids
Array of strings

Origin Private Dataset IDs

The private IDs of the Datasets to display all connections from.

filter.connected_datasets.private_ids
Array of strings

PrivateIds

The filter to be applied to the private IDs of the returned Datasets. Only Datasets with private IDs containing one of the strings specified in this filter will be returned. Case insensitive.

filter.connected_datasets.public_names
Array of strings

PublicNames

The filter to be applied to the public names of the returned Datasets. Only Datasets with public names containing one of the string specified in this filter will be returned. Case insensitive.

filter.connected_datasets.public_description
string

PublicDescription

The filter to be applied to the public descriptions of the returned Datasets. Only Datasets with public descriptions containing the string specified in this filter will be returned. Case insensitive.

filter.connected_datasets.create_time_filter.start_time
string <date-time>

Start

Defines the earliest time the filter is applied from. The filter matches all dates after this point in time, inclusive.

filter.connected_datasets.create_time_filter.end_time
string <date-time>

End

Defines the time the filter is applied until. The filter matches all dates before this point in time, inclusive.

filter.connected_datasets.owner_ids
Array of strings

Owner User IDs

Filters Datasets on the specified owner user IDs.

filter.connected_datasets.categories.ids
Array of strings <int64> [ items <int64 > ]

Ids

The IDs of the Categories that must be present in the Dataset.

filter.connected_datasets.categories.min_fill_rates
Array of numbers <double> [ items <double > ]

MinFillRates

The minimum fill rates for each category specified in Ids. These are inclusive of the bound. A value must be specified for each Category. If the user doesn't want to filter by fill rate, they can set the minimum fill rate to 0, which will match all fill rate values. Values should be in the range 0 to 1, inclusive.

filter.connected_datasets.project_ids
Array of strings

ProjectIds

The filter to be applied to the projects associated with the returned Datasets. Only Datasets within projects matching one of the project ids specified in this filter will be returned. Case insensitive.

filter.min_intersection
number <double>

Min Intersection

The lowest acceptable intersection relative to the size of the connected Dataset. This is calculated by taking the number of rows in the from Dataset that are also in the to Dataset when using the 'best' key, and diving by the total number of rows in the from Dataset. Values can be between 0 and 1, inclusive. If omitted, any intersection will be allowed.

sort.by
string

By is the field to sort by.

sort.order
string
Default: "ASCENDING"
Enum: "ASCENDING" "DESCENDING"

Order is the order to sort in. Defaults to ascending.

  • ASCENDING: Sort in ascending order.
  • DESCENDING: Sort in descending order.

Responses

Response samples

Content type
application/json
{
  • "connections": [
    ],
  • "datasets": [
    ]
}

Get metadata for a Connection

Gets metadata for a specific Connection between two Datasets.

Authorizations:
API_Keys
path Parameters
first_private_id
required
string

First Private Datasets ID

The Private ID of the first Dataset in this Connection.

second_private_id
required
string

Second Datasets ID

The Private ID of the second Dataset in this Connection.

Responses

Response samples

Content type
application/json
{
  • "connection": {
    }
}

Datasets

List Datasets

Lists Datasets the user has access to.

Authorizations:
API_Keys
query Parameters
filter.ownership
string
Default: "ANY_OWNERSHIP"
Enum: "ANY_OWNERSHIP" "OWNED" "NOT_OWNED"

OwnershipFilter

Specifies whether to return all Datasets, or only those that are owned or not owned by the requesting user.

  • ANY_OWNERSHIP: Returns all Datasets the user has access to.
  • OWNED: Only returns Datasets owned by the user.
  • NOT_OWNED: Only returns Datasets not owned by the user.
filter.datasets.private_ids
Array of strings

PrivateIds

The filter to be applied to the private IDs of the returned Datasets. Only Datasets with private IDs containing one of the strings specified in this filter will be returned. Case insensitive.

filter.datasets.public_names
Array of strings

PublicNames

The filter to be applied to the public names of the returned Datasets. Only Datasets with public names containing one of the string specified in this filter will be returned. Case insensitive.

filter.datasets.public_description
string

PublicDescription

The filter to be applied to the public descriptions of the returned Datasets. Only Datasets with public descriptions containing the string specified in this filter will be returned. Case insensitive.

filter.datasets.create_time_filter.start_time
string <date-time>

Start

Defines the earliest time the filter is applied from. The filter matches all dates after this point in time, inclusive.

filter.datasets.create_time_filter.end_time
string <date-time>

End

Defines the time the filter is applied until. The filter matches all dates before this point in time, inclusive.

filter.datasets.owner_ids
Array of strings

Owner User IDs

Filters Datasets on the specified owner user IDs.

filter.datasets.categories.ids
Array of strings <int64> [ items <int64 > ]

Ids

The IDs of the Categories that must be present in the Dataset.

filter.datasets.categories.min_fill_rates
Array of numbers <double> [ items <double > ]

MinFillRates

The minimum fill rates for each category specified in Ids. These are inclusive of the bound. A value must be specified for each Category. If the user doesn't want to filter by fill rate, they can set the minimum fill rate to 0, which will match all fill rate values. Values should be in the range 0 to 1, inclusive.

filter.datasets.project_ids
Array of strings

ProjectIds

The filter to be applied to the projects associated with the returned Datasets. Only Datasets within projects matching one of the project ids specified in this filter will be returned. Case insensitive.

sort.by
string

By is the field to sort by.

sort.order
string
Default: "ASCENDING"
Enum: "ASCENDING" "DESCENDING"

Order is the order to sort in. Defaults to ascending.

  • ASCENDING: Sort in ascending order.
  • DESCENDING: Sort in descending order.

Responses

Response samples

Content type
application/json
{
  • "datasets": [
    ]
}

Get Dataset metadata

Gets metadata for a specific Dataset the user owns or has access to.

Authorizations:
API_Keys
path Parameters
private_id
required
string

Private Dataset ID

The Private ID of the Dataset to retrieve, as assigned by the user.

Responses

Response samples

Content type
application/json
{
  • "dataset": {
    },
  • "schema": {
    }
}

Get Dataset credit usage

Gets a time series of credit usage on the specified Dataset.

Authorizations:
API_Keys
path Parameters
private_id
required
string

Private Dataset ID

The Private ID of the Dataset to return usage data for.

query Parameters
start_time
string <date-time>

Start Time

The timestamp from which to return usage data. If not specified, will default to the beginning of the current month. If specified, the StartTime will be rounded down to the next group boundary as specified by Grouping.

end_time
string <date-time>

End Time

The timestamp up to which to return usage data. If not specified, will return all data up to the present moment. The EndTime will be rounded up to the next group boundary as specified by Grouping.

grouping
string
Default: "TIME_GROUPING_UNSPECIFIED"
Enum: "TIME_GROUPING_UNSPECIFIED" "DAY" "WEEK" "MONTH" "YEAR"

Grouping

Specifies how to roll up a time series into discrete groups.

  • TIME_GROUPING_UNSPECIFIED: Default value - should not be used.
  • DAY: All values within a single day will be rolled up into a single datapoint.
  • WEEK: All values within a single week (Monday - Sunday) will be rolled up into a single datapoint.
  • MONTH: All values within a single calendar month will be rolled up into a single datapoint.
  • YEAR: All values within a single calendar year will be rolled up into a single datapoint.

Responses

Response samples

Content type
application/json
{
  • "timeseries": [
    ]
}

Demo Datasets

Remove access to the Demo Datasets

Remove access to the Demo Datasets.

Authorizations:
API_Keys

Responses

Response samples

Content type
application/json
{ }

Add access to the Demo Datasets

Add access to the Demo Datasets for querying.

Authorizations:
API_Keys
Request Body schema: application/json
required

Used to add Demo Datasets with the AddDemoDatasets method.

object (Add Demo Datasets Request)

Used to add Demo Datasets with the AddDemoDatasets method.

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "permissions": [
    ]
}

Queries

ExplainQuery explains how a query will be executed.

Provides information about the choices made by the platform before executing a query.

Authorizations:
API_Keys
Request Body schema: application/json
required

Used to explain the choices made by the platform before executing a query.

query
string (Query)

The Query whose execution will be explained. This takes the format of an InfoSum Query Language Query. See the documentation of the InfoSum Query Language for more information.

Array of objects (Path Overrides)

A list of instructions on how to connect two datasets, overriding the automatic choices made by the core engine.

Responses

Request samples

Content type
application/json
{
  • "query": "string",
  • "path_overrides": [
    ]
}

Response samples

Content type
application/json
{
  • "query_plan": {
    },
  • "hop_table": [
    ]
}

Create a Query

Queue a Query for execution. Returns immediately with an ID of the Query created.

Authorizations:
API_Keys
Request Body schema: application/json
required

Used to create a Query with the CreateQuery method.

query
string (Query)

The Query that should be queued. This takes the format of an InfoSum Query Language Query. See the documentation of the InfoSum Query Language for more information.

Array of objects (Path Overrides)

A list of instructions on how to connect two datasets, overriding the automatic choices made by the core engine.

sample
boolean (Sample)

A flag that can be used to execute the query against a smaller sample of the data. Can be used to reduce the execution time for a less accurate result.

Array of objects (Count Overrides)

A list of dataset IDs with an ordered list of keys to be used when calculating a count on that dataset.

Responses

Request samples

Content type
application/json
{
  • "query": "string",
  • "path_overrides": [
    ],
  • "sample": true,
  • "count_overrides": [
    ]
}

Response samples

Content type
application/json
{
  • "query_id": "string",
  • "done": true
}

Get a Query

Get the current status of the Query.

Authorizations:
API_Keys
path Parameters
query_id
required
string

Query ID

The ID of the Query, as returned from the CreateQuery method.

Responses

Response samples

Content type
application/json
{
  • "query_id": "string",
  • "done": true
}

Get a Result

Get the Result of a Query, when it is available.

Authorizations:
API_Keys
path Parameters
query_id
required
string

Query ID

The ID of the Query, as returned from the CreateQuery method.

Responses

Response samples

Content type
application/json
{
  • "dimensions": [
    ],
  • "audience": 0,
  • "quality_measures": {
    },
  • "join_metadata": [
    ],
  • "count_metadata": [
    ]
}

ValidateQuery validates a query

Performs validation of a query without actually executing it. Good for testing that your queries are correctly formatted.

Authorizations:
API_Keys
Request Body schema: application/json
required

Used to validate a Query before executing it.

query
string (Query)

The Query that should be validated. This takes the format of an InfoSum Query Language Query. See the documentation of the InfoSum Query Language for more information.

Array of objects (Path Overrides)

A list of instructions on how to connect two datasets, overriding the automatic choices made by the core engine.

Responses

Request samples

Content type
application/json
{
  • "query": "string",
  • "path_overrides": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true
}

Health

Checks the health of the service

Returns the health status of the service.

Authorizations:
API_Keys

Responses

Response samples

Content type
application/json
{
  • "status": "UNKNOWN"
}

Permissions

List all Permissions associated with the User.

List all Permissions the user has offered or been offered.

Authorizations:
API_Keys
query Parameters
filter.direction
string
Default: "ANY_DIRECTION"
Enum: "ANY_DIRECTION" "INCOMING" "OUTGOING"

Direction

Specifies whether to return all Permissions, or only those that are incoming or outgoing.

  • ANY_DIRECTION: Shows all Permissions.
  • INCOMING: Only shows incoming Permissions.
  • OUTGOING: Only shows outgoing Permissions.
filter.accepted
string
Default: "ANY_ACCEPTED"
Enum: "ANY_ACCEPTED" "INACTIVE" "ACTIVE"

Accepted

Specifies whether to return all Permissions, or only those that have or have not been accepted by the recipient.

  • ANY_ACCEPTED: Shows all Permissions.
  • INACTIVE: Only shows inactive Permissions.
  • ACTIVE: Only shows active Permissions.
filter.owned_datasets.private_ids
Array of strings

PrivateIds

The filter to be applied to the private IDs of the returned Datasets. Only Datasets with private IDs containing one of the strings specified in this filter will be returned. Case insensitive.

filter.owned_datasets.public_names
Array of strings

PublicNames

The filter to be applied to the public names of the returned Datasets. Only Datasets with public names containing one of the string specified in this filter will be returned. Case insensitive.

filter.owned_datasets.public_description
string

PublicDescription

The filter to be applied to the public descriptions of the returned Datasets. Only Datasets with public descriptions containing the string specified in this filter will be returned. Case insensitive.

filter.owned_datasets.create_time_filter.start_time
string <date-time>

Start

Defines the earliest time the filter is applied from. The filter matches all dates after this point in time, inclusive.

filter.owned_datasets.create_time_filter.end_time
string <date-time>

End

Defines the time the filter is applied until. The filter matches all dates before this point in time, inclusive.

filter.owned_datasets.owner_ids
Array of strings

Owner User IDs

Filters Datasets on the specified owner user IDs.

filter.owned_datasets.categories.ids
Array of strings <int64> [ items <int64 > ]

Ids

The IDs of the Categories that must be present in the Dataset.

filter.owned_datasets.categories.min_fill_rates
Array of numbers <double> [ items <double > ]

MinFillRates

The minimum fill rates for each category specified in Ids. These are inclusive of the bound. A value must be specified for each Category. If the user doesn't want to filter by fill rate, they can set the minimum fill rate to 0, which will match all fill rate values. Values should be in the range 0 to 1, inclusive.

filter.owned_datasets.project_ids
Array of strings

ProjectIds

The filter to be applied to the projects associated with the returned Datasets. Only Datasets within projects matching one of the project ids specified in this filter will be returned. Case insensitive.

filter.other_datasets.private_ids
Array of strings

PrivateIds

The filter to be applied to the private IDs of the returned Datasets. Only Datasets with private IDs containing one of the strings specified in this filter will be returned. Case insensitive.

filter.other_datasets.public_names
Array of strings

PublicNames

The filter to be applied to the public names of the returned Datasets. Only Datasets with public names containing one of the string specified in this filter will be returned. Case insensitive.

filter.other_datasets.public_description
string

PublicDescription

The filter to be applied to the public descriptions of the returned Datasets. Only Datasets with public descriptions containing the string specified in this filter will be returned. Case insensitive.

filter.other_datasets.create_time_filter.start_time
string <date-time>

Start

Defines the earliest time the filter is applied from. The filter matches all dates after this point in time, inclusive.

filter.other_datasets.create_time_filter.end_time
string <date-time>

End

Defines the time the filter is applied until. The filter matches all dates before this point in time, inclusive.

filter.other_datasets.owner_ids
Array of strings

Owner User IDs

Filters Datasets on the specified owner user IDs.

filter.other_datasets.categories.ids
Array of strings <int64> [ items <int64 > ]

Ids

The IDs of the Categories that must be present in the Dataset.

filter.other_datasets.categories.min_fill_rates
Array of numbers <double> [ items <double > ]

MinFillRates

The minimum fill rates for each category specified in Ids. These are inclusive of the bound. A value must be specified for each Category. If the user doesn't want to filter by fill rate, they can set the minimum fill rate to 0, which will match all fill rate values. Values should be in the range 0 to 1, inclusive.

filter.other_datasets.project_ids
Array of strings

ProjectIds

The filter to be applied to the projects associated with the returned Datasets. Only Datasets within projects matching one of the project ids specified in this filter will be returned. Case insensitive.

sort.by
string

By is the field to sort by.

sort.order
string
Default: "ASCENDING"
Enum: "ASCENDING" "DESCENDING"

Order is the order to sort in. Defaults to ascending.

  • ASCENDING: Sort in ascending order.
  • DESCENDING: Sort in descending order.

Responses

Response samples

Content type
application/json
{
  • "permissions": [
    ]
}

Get Permission credit usage

Gets a time series of credit usage on the specified Dataset.

Authorizations:
API_Keys
path Parameters
private_id
required
string

Private Dataset ID

The Private ID of the Dataset that the Permission is from, which identifies the Permission to return usage data for when combined with RecipientId.

recipient_id
required
string

Recipient user ID

The user ID of the recipient of the Permission to return usage data for, which identifies a single Permission when combined with Dataset ID.

query Parameters
start_time
string <date-time>

Start Time

The timestamp from which to return usage data. If not specified, will default to the beginning of the current month. If specified, the StartTime will be rounded down to the next group boundary as specified by Grouping.

end_time
string <date-time>

End Time

The timestamp up to which to return usage data. If not specified, will return all data up to the present moment. The EndDate will be rounded up to the next group boundary as specified by Grouping.

grouping
string
Default: "TIME_GROUPING_UNSPECIFIED"
Enum: "TIME_GROUPING_UNSPECIFIED" "DAY" "WEEK" "MONTH" "YEAR"

Grouping

Specifies how to roll up a time series into discrete groups.

  • TIME_GROUPING_UNSPECIFIED: Default value - should not be used.
  • DAY: All values within a single day will be rolled up into a single datapoint.
  • WEEK: All values within a single week (Monday - Sunday) will be rolled up into a single datapoint.
  • MONTH: All values within a single calendar month will be rolled up into a single datapoint.
  • YEAR: All values within a single calendar year will be rolled up into a single datapoint.

Responses

Response samples

Content type
application/json
{
  • "timeseries": [
    ]
}