Export API

09 Aug 2024
15 Minutes to read
Contributors

Print
Share
Dark
Light
PDF

Export API

Updated on 09 Aug 2024
15 Minutes to read
Contributors

Print
Share
Dark
Light
PDF

Article summary

Did you find this summary helpful?

Thank you for your feedback

Getting Started

This guide will help you get started with using our APIs, understand the prerequisites, and provide detailed information on each API endpoint.

Register for an API Key: Obtain your API key by registering on our platform.
Set Up Your Environment: Ensure you have the necessary tools and libraries installed (e.g., Postman for testing APIs, Node.js for running scripts).
Make Your First API Call: Use the provided examples to make your first API call and retrieve data.

Prerequisites

Before you start using our APIs, ensure you have the following:

API Key: A valid API key for authentication.
Environment: Ensure you have an internet connection and the required tools (e.g., Postman, cURL).
Knowledge of GraphQL: Basic understanding of GraphQL queries and mutations.

Authentication

All API requests require an API key for authentication. Include your API key in the request header as shown below:

Authorization: Bearer YOUR_API_KEY

API Endpoints

ListUsers

Description

Retrieve a list of users based on specified filters.

Endpoint

POST /graphql

Query Example 1

query ListUsers {
    listUsers(first: 100, dateRanges: { dateField: registeredOn or updateDate, before: "2024-04-19", after: "2023-04-29" }) {
        usersCount
        users {
            id
            email
            phoneNumber
            isActive
            site
        }
    }
}

Query Breakdown Table:

Field/Component	Description
Query Name	`ListUsers`
Purpose	Retrieves a list of users who registered or were updated between specific dates.
Arguments
`first: 100`	Limits the result to the first 100 users.
`dateRanges`	Filters users based on their registration or update dates within the specified range.
`dateField: registeredOn or updateDate`	The field used for filtering users; can be `registeredOn` or `updateDate`.
`before: "2024-04-19"`	The latest date for the filter; only users registered/updated before this date are included.
`after: "2023-04-29"`	The earliest date for the filter; only users registered/updated after this date are included.

Query Example 2

query ListUsers {
    listUsers(first: 100, emails: ["xxx@gmail.com","xxx@yahoo.com"]) {
        usersCount
        users {
            id
            email
            phoneNumber
        }
    }
}

Query Breakdown Table:

Field/Component	Description
Query Name	`ListUsers`
Purpose	Retrieves a list of users with specific email addresses.
Arguments
`first: 100`	Limits the result to the first 100 users.
`emails: ["xxx@gmail.com","xxx@yahoo.com"]`	Filters users based on the specified email addresses.
Response Fields
`usersCount`	Total number of users returned by the query.
users	List of user objects with the following fields:
`id`	Unique identifier of the user.
`email`	Email address of the user.
`phoneNumber`	Phone number of the user.

Description

Retrieve a list of watched streams for users within a specified time range.

Endpoint

POST /graphql

Query Example

query ListUserWatched {
    listUserWatched(
        offset: 100
        limit: 1000
        watchTimeFrom: "2024-01-01"
        watchTimeTo: "2024-02-01"
    ) {
        totalCount
        totalWatchedStreams
        pageInfo {
            hasNextPage
            startCursor
            endCursor
        }
        watchedStreams {
            streamId
            contentId
            userId
            platform
            watchTime
            duration
            browser
            deviceName
            country
            cityname
            latitude
            longitude
            postalcode
            metrocode
            subdivisionIsoCode
            subdivisionName
            environment
        }
    }
}

Query Breakdown Table:

Field/Component	Description
Query Name	`ListUserWatched`
Purpose	Retrieves a list of watched streams by users within a specified time range.
Arguments
`offset: 100`	Skips the first 100 results (for pagination).
`limit: 1000`	Limits the result to 1000 watched streams.
`watchTimeFrom: "2024-01-01"`	Filters streams watched from January 1, 2024, onwards.
`watchTimeTo: "2024-02-01"`	Filters streams watched up to February 1, 2024.
Response Fields
`totalCount`	Total number of watched streams returned by the query.
`totalWatchedStreams`	Total count of watched streams within the result set.
pageInfo	Provides pagination information:
`hasNextPage`	Indicates if there are more pages of results.
`startCursor`	Cursor for the start of the current page.
`endCursor`	Cursor for the end of the current page.
watchedStreams	List of watched stream objects with the following fields:
`streamId`	Unique identifier of the stream.
`contentId`	Unique identifier of the content.
`userId`	Unique identifier of the user who watched the stream.
`platform`	Platform used to watch the stream (e.g., web, mobile).
`watchTime`	Date and time when the stream was watched.
`duration`	Duration of the watched stream in seconds.
`browser`	Browser used to watch the stream.
`deviceName`	Name of the device used to watch the stream.
`country`	Country where the stream was watched.
`cityname`	City where the stream was watched.
`latitude`	Latitude of the watch location.
`longitude`	Longitude of the watch location.
`postalcode`	Postal code of the watch location.
`metrocode`	Metro code of the watch location.
`subdivisionIsoCode`	ISO code of the subdivision (e.g., state, province).
`subdivisionName`	Name of the subdivision.
`environment`	Environment in which the stream was watched (e.g., production, staging).

ListContents

Description

Retrieve a list of contents based on specified filters.

Endpoint

POST /graphql

Query Example 1

query ListContents {
    listContents(
        first: 10
        after: "10"
        updatedRange: { before: "2024-01-01", after: "2023-12-01" }
    ) {
        contentCount
        contents {
            id
            type
            title
            permalink
            status
            publishDate
        }
    }
}

Query Breakdown Table:

Field/Component	Description
Query Name	`ListContents`
Purpose	Retrieves a list of contents based on specified criteria.
Arguments
`first: 10`	Limits the results to the first 10 contents.
`after: "10"`	Starts fetching results after the 10th item (pagination).
`updatedRange`	Filters contents based on their update date:
`before: "2024-01-01"`	Only includes contents updated before January 1, 2024.
`after: "2023-12-01"`	Only includes contents updated after December 1, 2023.
Response Fields
`contentCount`	Total number of contents that match the query criteria.
`contents`	List of content objects with the following fields:
`id`	Unique identifier for each content.
`type`	Type of the content (e.g., article, video).
`title`	Title of the content.
`permalink`	Permanent URL or link to the content.
`status`	Current status of the content (e.g., published, draft).
`publishDate`	Date when the content was published.

Query Example 2

query ListContents {
    listContents(
        first: 10
        after: "10"
        updatedRange: { before: "2024-01-01", after: "2023-12-01" }
        publishDateRange: { before: "2024-01-01", after: "2023-12-01" }
        type: video
    ) {
        contentCount
        contents {
            id
            type
            title
            permalink
            status
            publishDate
        }
    }
}

Query Breakdown Table:

Field/Component	Description
Query Name	`ListContents`
Purpose	Retrieves a list of video contents based on specified criteria.
Arguments
`first: 10`	Limits the results to the first 10 content items.
`after: "10"`	Starts fetching results after the 10th item (pagination).
`updatedRange`	Filters contents based on their update date:
`before: "2024-01-01"`	Only includes contents updated before January 1, 2024.
`after: "2023-12-01"`	Only includes contents updated after December 1, 2023.
`publishDateRange`	Filters contents based on their publish date:
`before: "2024-01-01"`	Only includes contents published before January 1, 2024.
`after: "2023-12-01"`	Only includes contents published after December 1, 2023.
`type: video`	Only includes contents of the type "video".
Response Fields
`contentCount`	Total number of contents that match the query criteria.
`contents`	List of content objects with the following fields:
`id`	Unique identifier for each content.
`type`	Type of the content (e.g., video).
`title`	Title of the content.
`permalink`	Permanent URL or link to the content.
`status`	Current status of the content (e.g., published, draft).
`publishDate`	Date when the content was published.

ListPayments

Description

Retrieve a list of payments based on specified date ranges.

Endpoint

POST /graphql

Query Example

query ListPayments {
    listPayments(
        dateRanges:{ 
        dateField: loadtime
        before: 2024-04-19
        after: 2024-04-29
    }) {
        billingHistory {
            userId
            id
            billingCyclePeriodMultiplier
            billingCyclePeriodType
            chargedAmountCurrencyCode
            completedAt
            description
            preTaxAmount
            subscriptionPlanId
            taxAmount
            type
            updateDate
            gatewayChargeId
            servicePeriodFrom
            servicePeriodTo
            paymentHandlerFee
            paymentHandler
            contentId
            contentType
            purchaseType
            videoQuality
            monetizationModel
            loadtime
        }
    }
}

Query Breakdown Table:

Field/Component	Description
Query Name	`ListPayments`
Purpose	Retrieves a list of payment records based on the specified criteria.
Arguments
`dateRanges`	Filters payments based on their load time:
`dateField: loadtime`	Specifies that the filter is based on the `loadtime` field.
`before: 2024-04-19`	Only includes payments with a load time before April 19, 2024.
`after: 2024-04-29`	Only includes payments with a load time after April 29, 2024.
Response Fields
`billingHistory`	List of payment records with the following details:
`userId`	Unique identifier for the user who made the payment.
`id`	Unique identifier for the payment record.
`billingCyclePeriodMultiplier`	Multiplier for the billing cycle period (e.g., number of months).
`billingCyclePeriodType`	Type of billing cycle period (e.g., monthly, yearly).
`chargedAmountCurrencyCode`	Currency code for the charged amount (e.g., USD).
`completedAt`	Date and time when the payment was completed.
`description`	Description of the payment.
`preTaxAmount`	Amount charged before tax.
`subscriptionPlanId`	Identifier for the subscription plan associated with the payment.
`taxAmount`	Amount of tax applied to the payment.
`type`	Type of payment (e.g., subscription, one-time purchase).
`updateDate`	Date when the payment record was last updated.
`gatewayChargeId`	Identifier for the charge from the payment gateway.
`servicePeriodFrom`	Start date of the service period covered by the payment.
`servicePeriodTo`	End date of the service period covered by the payment.
`paymentHandlerFee`	Fee charged by the payment handler.
`paymentHandler`	Name of the payment handler (e.g., PayPal, Stripe).
`contentId`	Identifier for the content associated with the payment.
`contentType`	Type of content associated with the payment (e.g., video, article).
`purchaseType`	Type of purchase made (e.g., one-time, subscription).
`videoQuality`	Quality of the video (if applicable).
`monetizationModel`	Model used for monetizing the content (e.g., ad-supported, subscription).
`loadtime`	Date and time when the payment was loaded into the system.

ListSubscriptions

Description

Retrieve a list of subscriptions based on specified date ranges.

Endpoint

POST /graphql

Query Example

Query 1: Retrieving Subscriptions by `addedDate`

Description: This query fetches subscriptions that were added within a specific date range. The addedDate refers to the date when the subscription was first created in the system.

Query Example:

graphqlCopy codequery ListSubscriptionsByAddedDate {
    listSubscriptions(
        dateRanges: {
            dateField: addedDate 
            before: "2024-04-30"
            after: "2024-04-29"
        }
    ) {
        subscriptions {
            userId
            ipAddress
            platform
            status
            startDate
            endDate
            email
            planId
            planIdentifier
            plan {
                planDetails {
                    title
                }
            }
        }
    }
}

Query Breakdown Table:

Component	Description
Query Name	`ListSubscriptionsByAddedDate`
Endpoint	`POST /graphql`
Purpose	Retrieve a list of subscriptions added within a specific date range.
Parameters
`dateRanges`	Filters to specify date range for when subscriptions were added.
`dateField`	Field to filter on (e.g., `addedDate`).
`before`	Date before which to include subscriptions (e.g., "2024-04-30").
`after`	Date after which to include subscriptions (e.g., "2024-04-29").

Query 2: Retrieving Subscriptions by `updateDate`

Description: This query fetches subscriptions that were updated within a specific date range. The updateDate refers to the date when the subscription was last modified or updated in the system.

Query Example:

graphqlCopy codequery ListSubscriptionsByUpdateDate {
    listSubscriptions(
        dateRanges: {
            dateField: updateDate 
            before: "2024-04-30"
            after: "2024-04-29"
        }
    ) {
        subscriptions {
            userId
            ipAddress
            platform
            status
            startDate
            endDate
            email
            planId
            planIdentifier
            plan {
                planDetails {
                    title
                }
            }
        }
    }
}

Query Breakdown Table:

Component	Description
Query Name	`ListSubscriptionsByUpdateDate`
Endpoint	`POST /graphql`
Purpose	Retrieve a list of subscriptions updated within a specific date range.
Parameters
`dateRanges`	Filters to specify date range for the updates.
`dateField`	Field to filter on (e.g., `updateDate`).
`before`	Date before which to include updates (e.g., "2024-04-30").
`after`	Date after which to include updates (e.g., "2024-04-29").

ListPurchases

Description

Retrieve a list of purchases based on specified filters.

Endpoint

bashCopy codePOST /graphql

Query Example

query ListPurchases {
    listPurchases(
        first: 10
        dateRanges: [{ dateField: addedDate, before: "2024-05-30", after: "2024-04-20" }]
    ) {
        purchasesCount
        pageInfo {
            hasNextPage
            startCursor
            endCursor
        }
        purchases {
            id
            userId
            ipAddress
        }
    }
}

Query Breakdown Table:

Component	Description
Query Name	`ListPurchases`
Endpoint	`POST /graphql`
Purpose	Retrieve a list of purchases with pagination and filters.
Parameters
`first`	Number of purchases to return (e.g., 10).
`dateRanges`	Filters to specify date range for the purchases.
`dateField`	Field to filter on (e.g., `addedDate`).
`before`	Date before which to include purchases (e.g., "2024-05-30").
`after`	Date after which to include purchases (e.g., "2024-04-20").

Response Fields

Field	Type	Description
usersCount	`Int`	Total number of users retrieved.
totalCount	`Int`	Total number of items retrieved (e.g., watched streams, contents).
contentCount	`Int`	Total number of contents retrieved.
purchasesCount	`Int`	Total number of purchases retrieved.
pageInfo	`Object`	Pagination information.
hasNextPage	`Boolean`	Indicates if there are more pages of results.
startCursor	`String`	Cursor for the start of the page.
endCursor	`String`	Cursor for the end of the page.
users	`Array`	List of user objects.
watchedStreams	`Array`	List of watched stream objects.
contents	`Array`	List of content objects.
billingHistory	`Array`	List of payment objects.
subscriptions	`Array`	List of subscription objects.
id	`String`	Unique identifier of the item (e.g., user, stream, content, payment, purchase).
userId	`String`	Unique identifier of the user.
email	`String`	Email address associated with the item (e.g., user, subscription).
phoneNumber	`String`	Phone number of the user.
isActive	`Boolean`	Status of the user (active/inactive).
site	`String`	Site associated with the user.
streamId	`String`	Unique identifier of the stream.
contentId	`String`	Unique identifier of the content.
platform	`String`	Platform used (e.g., web, mobile).
watchTime	`String`	Time when the stream was watched.
duration	`Int`	Duration of the watched stream (in seconds).
browser	`String`	Browser used to watch the stream.
deviceName	`String`	Name of the device used.
country	`String`	Country where the stream was watched.
cityname	`String`	City where the stream was watched.
latitude	`Float`	Latitude of the watch location.
longitude	`Float`	Longitude of the watch location.
postalcode	`String`	Postal code of the watch location.
metrocode	`String`	Metro code of the watch location.
subdivisionIsoCode	`String`	ISO code of the subdivision.
subdivisionName	`String`	Name of the subdivision.
environment	`String`	Environment in which the stream was watched.
type	`String`	Type of the item (e.g., video, content).
title	`String`	Title of the item (e.g., plan, content).
permalink	`String`	Permalink URL of the content.
status	`String`	Status of the item (e.g., published, completed).
publishDate	`String`	Publish date of the content.
loadtime	`String`	Load time of the payment.
id	`String`	Unique identifier of the payment.
billingCyclePeriodMultiplier	`Int`	Multiplier for the billing cycle period.
billingCyclePeriodType	`String`	Type of billing cycle period.
chargedAmountCurrencyCode	`String`	Currency code of the charged amount.
completedAt	`String`	Date and time when the payment was completed.
description	`String`	Description of the payment.
preTaxAmount	`Float`	Pre-tax amount of the payment.
subscriptionPlanId	`String`	Unique identifier of the subscription plan.
taxAmount	`Float`	Tax amount of the payment.
type	`String`	Type of the payment.
updateDate	`String`	Date and time when the payment was last updated.
gatewayChargeId	`String`	Unique identifier of the gateway charge.
servicePeriodFrom	`String`	Start date of the service period.
servicePeriodTo	`String`	End date of the service period.
paymentHandlerFee	`Float`	Fee charged by the payment handler.
paymentHandler	`String`	Name of the payment handler.
contentId	`String`	Unique identifier of the content.
contentType	`String`	Type of the content.
purchaseType	`String`	Type of purchase.
videoQuality	`String`	Quality of the video content.
monetizationModel	`String`	Monetization model of the payment.

Error Handling

The API returns standardized error codes to help you diagnose and resolve issues quickly.

Error Code	Description	Suggested Action
400	Bad Request - Invalid syntax or missing parameters	Check the request syntax and parameters.
401	Unauthorized - Invalid API key	Verify your API key and authentication details.
403	Forbidden - Insufficient permissions	Ensure you have the required access rights.
404	Not Found - Resource does not exist	Verify the endpoint and resource identifiers.
429	Too Many Requests - Rate limit exceeded	Wait for the rate limit to reset.
500	Internal Server Error	Contact support if the issue persists.
503	Service Unavailable - API is temporarily offline	Retry after some time or contact support.

Best Practices
Follow these best practices to ensure optimal use of the API and minimize issues:
Efficient Use of Resources:
Paginate results for large datasets to avoid performance bottlenecks.
Cache frequently accessed data to reduce redundant API calls.
Handle Errors Gracefully:
Implement error handling in your application to manage API failures and rate limits.
Retry failed requests with exponential backoff to handle temporary network issues.
Keep API Keys Secure:
Store API keys securely and avoid hardcoding them in your application code.
Regularly rotate API keys and remove unused keys.
Test in a Staging Environment:
Use a staging environment to test API integration before deploying to production.
Monitor API usage and performance in real-time to detect issues early.

FAQ (Frequently Asked Questions)

1. How do I obtain an API key?

To obtain an API key, register on our platform and navigate to the API section in your account settings. Here, you can generate a new API key.

2. How do I authenticate my API requests?

Include your API key in the request header as follows:

Authorization: Bearer YOUR_API_KEY

3. What should I do if my API key is not working?

Ensure that your API key is correctly included in the request header. If the issue persists, check if the key has expired or been revoked in your account settings. For further assistance, contact our support team.

4. What is the rate limit for API requests?

The rate limit varies depending on your subscription plan. Refer to your plan details in the account settings or contact support for more information.

5. How do I paginate through results?

Most queries support pagination. Use the pageInfo field in the response to navigate through pages. Use startCursor and endCursor to retrieve subsequent or previous pages.

6. Can I filter results based on multiple criteria?

Yes, our API supports filtering results based on multiple criteria. Refer to the specific query examples in the documentation for details on how to apply filters.

7. What should I do if I receive an error response?

If you receive an error response, check the error message for details. Common issues include invalid API keys, incorrect query syntax, and exceeding rate limits. Refer to the Error Codes section for more information on resolving specific errors.

8. How do I retrieve only active users?

Use the isActive filter in your ListUsers query to retrieve only active users.

Example:

query ListActiveUsers {
    listUsers(first: 100, isActive: true) {
        usersCount
        users {
            id
            email
            phoneNumber
        }
    }
}

9. How can I get a list of all available content types?

Use the ListContents query without specifying a content type to retrieve a list of all available content types.

Example:

query ListAllContents {
    listContents(first: 10) {
        contentCount
        contents {
            id
            type
            title
        }
    }
}

10. Can I retrieve historical data for a specific date range?

Yes, you can retrieve historical data by specifying the before and after date fields in your query. Refer to the date range filters in the specific query examples for more details.

11. What happens if there are more results than the limit specified in the query?

If there are more results than the limit specified in the query, use the pagination information (hasNextPage, startCursor, endCursor) in the response to retrieve additional results.

Contact Support

For further assistance, please contact our support team:

Email: techsupport@viewlift.com
US: +1-800-859-0420
UK: +44-203-014-8921
Support Hours:
- B2C: Monday to Friday
- B2B: 24X7

Was this article helpful?

What's Next

Navigation Logo Specifications

Table of contents

Getting Started
Prerequisites
Authentication
API Endpoints
Response Fields
Error Handling
Best Practices
FAQ (Frequently Asked Questions)
Contact Support

Export API

Getting Started

Prerequisites

Authentication

API Endpoints

ListUsers

Description

Endpoint

Query Example 1

Query Breakdown Table:

Query Example 2

Query Breakdown Table:

Description

Endpoint

Query Example

Query Breakdown Table:

ListContents

Description

Endpoint

Query Example 1

Query Breakdown Table:

Query Example 2

Query Breakdown Table:

ListPayments

Description

Endpoint

Query Example

Query Breakdown Table:

ListSubscriptions

Description

Endpoint

Query Example

Query 1: Retrieving Subscriptions by addedDate

Query Breakdown Table:

Query 2: Retrieving Subscriptions by updateDate

Query Breakdown Table:

ListPurchases

Description

Endpoint

Query Example

Query Breakdown Table:

Response Fields

Error Handling

Best Practices

FAQ (Frequently Asked Questions)

1. How do I obtain an API key?

2. How do I authenticate my API requests?

3. What should I do if my API key is not working?

4. What is the rate limit for API requests?

5. How do I paginate through results?

6. Can I filter results based on multiple criteria?

7. What should I do if I receive an error response?

8. How do I retrieve only active users?

9. How can I get a list of all available content types?

10. Can I retrieve historical data for a specific date range?

11. What happens if there are more results than the limit specified in the query?

Contact Support

What's Next

Query 1: Retrieving Subscriptions by `addedDate`

Query 2: Retrieving Subscriptions by `updateDate`