Raw Export
devtodev RAW export API
To use RAW data export API you need to have an individual User API token, which can be found in the settings of space.

You’ll see the block with User API token on the space settings page only in case if your tariff plan and access rights allow to use devtodev API. You can reset User API token or create it again on the same page.

If some applications of the space are inaccessible to the owner of User API token, then the owner can’t get access to the export of data of these applications. But the access to specific metrics it not extended to the access of raw data.
Please attend, if you use several spaces, in every space user has an individual User API token.
The process of getting data consists of three steps:
- job assignment
- getting the status of performance
- getting the report file by link
Let’s have a look at these steps.
This step is the most important, and its description is the longest one.
The request of assignment should be sent to:
https://devtodev.com/api/v1/rawexport/setjob?user_token=USER_API_TOKEN
Where
- user_token - individual User API token of the user. It could be sent with both GET and POST methods.
- v1 - current version of API
The request content is sent with POST method in JSON format.
The body of the request contains the following properties:
Property | Type | Description |
user_token | string | Individual user API token. It can be found on the space settings page. It is possible to send it with both POST and GET methods. |
app_id | string | Application identificator. It can be found in the application settings in the Integration section. |
start_date | number | Start date of the request interval. Attention! Data is sent in UNIX-time format. Don’t forget to add/subtract the number of correction seconds to get data according to your timezone. |
end_date | number | End date of the request interval. Data is sent in UNIX-time format. |
events | array | List of events to export. The element of the array can be in the following formats:
The empty array means the export of all the available events. |
Every standard event in devtodev SDK corresponds with two-letters identificator. In case of custom events, the name of the event is the identificator. Also you can use group identificators (start with @).
Event ID | Event name |
lu | Level up |
rp | Real Payment |
tr | Tutorial step |
ip | Ingame purchase |
sc | Social network connect |
sp | Social network post |
gs | Sessions |
uu | User update |
ud | UDIDs |
pe | Progression event |
rg | Registration (install date) |
sbs | Subscription (all actions with subscriptions) |
adrv | Ad impressions. Data from ad networks or the Ad Impression event. |
@basic_events | All events below |
sbs_payments | Subscription (payments only) |
Any custom event name | Custom event |
@custom_events | All custom events |
If you’re interested in the export of custom events according to some specific conditions, you should set the objects with the following properties in the array of the event list:
Property | Type | Description |
name | string | Name of custom event |
filters | object | Object with the filtering conditions. Names of the object properties correspond with the name of custom event parameters. It is possible to apply filters to each of them. Example "filters":{
"paramName1":{
"gt": 5 // Events where paramName1>5. Have a look at List of comparison operators.
}
} |
alias | string | Name of file in the report where to put the event with filter. The default name is set in the “name” property. Attention! If you export several equal events with different filters, the “alias” property is obligatory. |
The filter can be described with an object, where the following comparison operators can be the properties:
API operator | Math operator | Description |
gt | > | Greater than |
lt | < | Less than |
eq | = | Equal |
gte | >= | Greater than or equal |
lte | <= | Less than or equal |
neq | != | Not equal |
eq | | In the list |
neq | | Not in the list |
The empty object describes the filter which selects all the events where the parameter value is not null or empty string.
https://devtodev.com/api/v1/rawexport/setjob
POST
{
"user_token": "USER_API_TOKEN", // It is obligatory, if it’s not sent with GET.
"app_id": "af0606ed-bbdc-065a-952c-0d92561f107c", // Obligatory. Application identificator.
"start_date": 1464709200, // Obligatory. Unix time of export start date.
"end_date": 1464739200, // Obligatory. Unix time of export end date.
"events": [ //Not obligatory. List of events to export.
"tr", // Export all Tutorial step events
"customEvent1Name", // Export all customEvent1Name events
//{"name": "customEvent1Name"} - alternative way with the same result
{
"name": "customEvent2Name",
"filters": { // Object with filter conditions
"paramName1": {
// 5<paramName1<=10 and paramName1!=8
"lte": 10,
"gt": 5,
"neq": 8
},
"paramName2": {
//Parameter paramName2 is equal to the one of elements.
"eq": ["a","b","c"]
},
"paramName3": {} // paramName3 is not empty.
}
}
]
}
Or another way with event group identificator.
{
"user_token": "USER_API_TOKEN",
"app_id": "af0606ed-bbdc-065a-952c-0d92561f107c",
"start_date": 1464709200,
"end_date": 1464739200,
"events": ["@custom_events"] //Export all custom events
}
The response in case of successful start execution:
{
"status_code": 200,
"data": "JOB_ID"
}
Where
- status_code - is the HTTP status code
- data - an identificator which is assigned to the job
If you get this response, you can go to the next stage - request of job status (else go to Error handling).
With the job identificator, you can request its current status, using the following request:
https://devtodev.com/api/v1/rawexport/getprogress?user_token=USER_API_TOKEN
The body of request can contain the following properties:
Property | Type | Description |
user_token | string | Individual user API token. It can be found on the space settings page. It is possible to send it with both POST and GET methods. |
job_id | string | Job identificator which can be got from the response of job assignment. |
The response to the request of status can be one of the following:
- The job is in the queue
- The job is in progress
- The job is done
- Error of job performance
Let’s explore every variant.
{
"status_code":202,
"data":{
"status":"pending",
"percent_complete":0
}
}
{
"status_code":200,
"data":{
"status":"running",
"percent_complete":10
}
}
{
"status_code":201,
"data":{
"status":"complete",
"percent_complete":100,
"result":{
"msg":"Report file is ready",
"format":"csv", // Format of report files in archive
"url":"https://devtodev.com/api/v1/rawexport/download/?job_id=JOB_ID&user_token=USER_API_TOKEN",
"ttl": 100500, // Report lifetime from the end of the performance to the removal
"expire":123434534534 // Date when the report will be removed (in UNIX-time format)
}
}
}
To get the report use the link in the URL property.
The report file is zip-archive with files in .CSV format. Every file contains data about one event and/or alias (which was set in the filter in job assignment).
If there are no events according to the query conditions, the response will be the following:
{
"status_code":200,
"data":{
"status":"complete",
"percent_complete":100,
"result":{
"msg":"Unfortunately the result of your request is empty. Please try to change the report conditions."
}
}
}
The error can raise either at the moment of job assignment or at the moment of checking the status.
The format of response in case of error is the same:
In case there is an error, a response is made in the following format:
{
"status_code": 400,
"errors": [{
"code": 3,
"msg": "Error description"
}]
}
where
- status_code (number) - a general status of an error
- errors (array) - an array of error descriptions
- code (number) - the exact code of an error from the table of errors
- msg (string) - a brief description of an error
The list of possible errors is given in a table.
Status code | Code | Value of "msg" field | Error description |
400 | 2 | Request body is empty | Empty body of the request. There is no POST data in the request. |
400 | 3 | Malformed json | JSON error in the body of the equest. Fix the formatting error. |
401 | 11 | Authorization error. Wrong user token %user_token value% | Authorization error. The set token is wrong. “User_token” field. User API token. |
401 | 12 | Authorization error. User_token is not set. | Authorization error. “User_token” field is absent. User API token should be set either as a parameter in GET string of request or in POST body of request. |
400 | 6 | Invalid app id %app id value% | The requested project can not be found. Unknown application. This error can raise when a user makes a mistake with the app id or when the application with this ID was removed. |
403 | 13 | Access denied. You have no access to the app %app id value% | The error of access. User has no access to this application. |
403 | 14 | Access denied. You have no access to the report file %file id value% | The error of access. User has no access to this file. This error can raise if you have no access to the application used in the previously created request. |
403 | 15 | Access denied. You have no access to API. | The error of access. No access to User API token. This error can happen when the access rights were changed (in consequence of changing the user role or tariff plan) |
403 | 16 | Access denied. You have no access to RAW data export API. | The error of access. This error can raise when you have no rights to RAW data export API for your user role or tariff plan. |
400 | 4 | Field not found: %field_name% | An obligatory field can not be found. You need to complement the request with this field. |
403 | 17 | Quota exceeded. %% concurrent requests per user has been reached. | The limit of simultaneous jobs per user is exceeded. Wait until one of the jobs will be finished and repeat the request. |
429 | 18 | Too many requests. %% requests per day per user quota has been exhausted. | The daily limit of the user is exceeded. You can send the next request at the beginning of the next day. |
429 | 19 | Too many requests. %% requests per day per space quota has been exhausted. | The daily space limit is exceeded. You can send the next request at the beginning of the next day. |
429 | 20 | Too many requests. One request per %% seconds per user quota has been exhausted. | The limit of request frequency is exceeded. You have to wait for the time set in the error text. |
404 | 21 | File not found. The requested report file had been expired and was deleted. | The requested file can not be found. This can be when the file was removed due to the end of its lifetime. You have to repeat the job assignment and wait for the new file. |
400 | 10 | Incorrect report time frame interval: start_date and end_date can not be earlier than 90 days from now. | Incorrect report time frame interval. Both start and end date should be later than 90 days from now. |
400 | 22 | The job_id you requested is not found. | The job_id you requested is not found or the job was done and the report lifetime is exceeded. |
400 | 5 | Field %field_name% has type %received_type% but %expected_type% expected | The data type is not equal to the expected data type. Check the correspondence of the request with the format set in the documentation. Possible data types: boolean, integer, float, number (integer+float), string. |
400 | 7 | Unknown format: %format% | You have set the unknown export file format. |
400 | 9 | Event alias duplicated: %alias% | The event alias is duplicated. There should be no equal custom events without alias and no equal aliases in the request. |
400 | 8 | Unknown event: %event_name% | Unknown event. This error can raise when the event is not in @basic_event group or the event doesn’t exist or the event is blocked custom event. |
500 | 1 | Unknown Error | Unknown error. Please contact devtodev technical support. |
There are the following limitations to devtodev RAW data export API:
Limitations | Value |
Max number of job assignments per 24 hours per space | 100 |
Max number of job assignments per 24 hours per user | 50 |
Max number of simultaneous job assignments per user | 5 |
Max timeout between user job assignments | 5 seconds |
Max time to perform one job | - |
Max lifetime of the report file | 24 hours |
Max number of report file downloads | 10 |
Below you can find the description of each table for events available for export.
This file is always attached to the exported file. The table contains a list of users who performed the exported events. It also contains their characteristics available at the time of the export.
Column name | Description |
---|---|
devtodev ID | Numeric user identifier in the projects’s Users table |
Main ID | Main user identifier |
Created | User registration date. Unix timestamp |
Paying | Flags payers |
Cheater | Flags cheaters |
Tester | Flags testers |
Level | Current user level |
AppVersion | Current app version |
Language | User’s device locale |
Country | User country (set by IP address) |
Device manufacturer | Device manufacturer |
Device name | Device trademark name |
Crossplatform User ID | User ID set by developer |
Channel | Acquisition. User acquisition channel |
InstallSource | Android. Android installer bundle |
User agent | User agent |
Screen resolution | Screen resolution of the device or app’s workspace |
OS version | Version of the operating system |
IDFV | iOS vendor identifier |
IDFA | iOS advertising identifier |
OPEN_UDID | OpenUDID |
username | User name. Preset using the User card |
useremail | User email. Preset using the User card |
userphoto | User photo url. Preset using the User card |
userphone | User telephone number. Preset using the User card |
AdCampaign | Acquisition. The name of the ad campaign that resulted in acquiring the user |
Time zone offset | User timezone offset from UTC in milliseconds |
OsVersion | Version of the user’s operating system |
segments | List of user custom segments containing this user. Segments separated by comma |
Agency | Acquisition. Ad mediator name (Sub-publisher) |
Keyword | Acquisition. Ad keywords and/or keywords that led to install |
Placement | Acquisition. Place where the ad unit is located |
Site | Acquisition. Website or app where the ad was placed |
Ad group | Acquisition. Name of ad group |
Ad | Acquisition. Name of ad unit/banner |
This file contains entries on session starts and user activity times for the selected export period. The table contains session starts (rows with filled count field) and time when the app was in focus (rows with filled avg_duration field).
Column name | Description |
---|---|
devtodev ID | Numeric user identifier in the project’s Users table |
time | Event (session start or end of activity) start date. Unix timestamp in milliseconds |
count | Session start |
avg_duration | Average duration of user activity (time the app was in focus) |
isTester | At the time of event start the user was a Tester |
cheat | At the time of event start the user was a Cheater |
level | User level at the time of event start |
install_date | User registration date. Unix timestamp |
This file contains entries on virtual purchases in the app.
Column name | Description |
---|---|
devtodev ID | Numeric user identifier in the project's Users table |
time | Event (session start or end of activity) start date. Unix timestamp in milliseconds |
level | User level at the time of event start |
item_type | Item category |
item | Item name |
count | Amount of items the user bought |
cheat | At the time of event start the user was a Cheater |
isTester | At the time of event start the user was a Tester |
install_date | User registration date. Unix timestamp |
Virtual currency name 1 | Amount of virtual currency spent on the item (overall) |
Virtual currency name N | Amount of virtual currency spent on the item (overall) |
A user registration event used in the devtodev database. Usually, the registration date is the same as the date of the first launch of the app.
Column name | Description |
---|---|
devtodev ID | Numeric user identifier in the project’s Users table |
install_date | User registration date. Unix timestamp |
Event for when the user reaches a certain game level.
Column name | Description |
---|---|
devtodev ID | Numeric user identifier in the project’s Users table |
time | Event (session start or end of activity) start date. Unix timestamp in milliseconds |
level | User level at the time of event start |
isTester | At the time of event start the user was a Tester |
cheat | At the time of event start the user was a Cheater |
install_date | User registration date. Unix timestamp |
spent | Amount of virtual currency spent by user on the previous level. List of currency names and amounts separated by comma. Example: “Coins: 90, Gold: 10” |
earned | Amount of virtual currency earned by user on the previous level. List of currency names and amounts separated by comma. Example: “Coins: 90, Gold: 10 |
balance | Amount of virtual currency on user balance at the time of reaching a new level. List of currency names and amounts separated by comma. Example: “Coins: 90, Gold: 10 |
bought | Amount of virtual currency bought by user for real currency on the previous level. List of currency names and amounts separated by comma. Example: “Coins: 90, Gold: 10 |
Some user properties updates for the selected export period. (devtodev ID, logged IP, os_version).
Column name | Description |
---|---|
devtodev ID | Numeric user identifier in the project’s Users table |
logged ip | User IP address. Last digit of the address is anonymized |
os_version | Version of the user operating system |
List of user transactions. Purchases for real currency.
Column name | Description |
---|---|
devtodev ID | Numeric user identifier in the project’s Users table |
date | Event (session start or end of activity) start date. Unix timestamp in milliseconds |
level | User level at the time of event start |
transaction_id | Unique transaction identifier |
transaction_name | Item name or SKU |
amount_in_usd | Amount of real currency spent by user. Converted into USD using exchange rate at the moment the event is received by the devtodev server |
status | Is transaction valid or not |
install_date | User registration date. Unix timestamp |
isTester | At the time of event start the user was a Tester |
cheat | At the time of event start the user was a Cheater |
This file contains a list of triggered Progression events.
Column name | Description |
---|---|
devtodev ID | Numeric user identifier in the project’s Users table |
time | Event (session start or end of activity) start date. Unix timestamp in milliseconds |
level | User level at the time of event start |
location | Game location name |
success | Is location successfully completed (true/false) |
prev_location | Name of the previous location |
duration | Time spent on completing the location |
difficulty | Location difficulty (numeric) |
isTester | At the time of event start the user was a Tester |
cheat | At the time of event start the user was a Cheater |
install_date | User registration date. Unix timestamp |
spent | Amount of virtual currency or resources spent by user upon completing the location. List of currency names and amounts separated by comma. Example: “Coins: 90, Gold: 10 |
earned | Amount of virtual currency or resources earned by user upon completing the location. List of currency names and amounts separated by comma. Example: “Coins: 90, Gold: 10 |
Social media connection events.
Column name | Description |
---|---|
devtodev ID | Numeric user identifier in the project’s Users table |
time | Event (session start or end of activity) start date. Unix timestamp in milliseconds |
level | User level at the time of event start |
social | Name of social media |
isTester | At the time of event start the user was a Tester |
cheat | At the time of event start the user was a Cheater |
install_date | User registration date. Unix timestamp |
Social media publication events.
Column name | Description |
---|---|
devtodev ID | Numeric user identifier in the projest’s Users table |
time | Event (session start or end of activity) start date. Unix timestamp in milliseconds |
level | User level at the time of event start |
social | Name of social media |
reason | Reason for publication or title of publication |
isTester | At the time of event start the user was a Tester |
cheat | At the time of event start the user was a Cheater |
install_date | User registration date. Unix timestamp |
Subscription events: buying, renewal, and refund. This file contains only subscription events that impact revenue.
Column name | Description |
---|---|
devtodev ID | Numeric user identifier in the project’s Users table |
date | Event (session start or end of activity) start date. Unix timestamp in milliseconds |
level | User level at the time of event start |
transaction_id | Unique transaction identifier |
transaction_name | Subscription name or SKU |
amount_in_usd | Amount of real currency spent by user. Converted into USD using exchange rate at the moment the event is received by the devtodev server |
install_date | User registration date. Unix timestamp |
isTester | At the time of event start the user was a Tester |
cheat | At the time of event start the user was a Cheater |
All subscription events.
Column name | Description |
---|---|
devtodev ID | Numeric user identifier in the project’s Users table |
date | Event (session start or end of activity) start date. Unix timestamp in milliseconds |