S3 Player Data Export
Overview Enterprise
Section titled “Overview ”Player Data Export writes your game’s player records to an Amazon S3 bucket you own. Use these records in your data warehouse or reporting pipeline to connect FirstLook player information with your own game and business data.
Each export run writes the current player records as JSON Lines (JSONL) files, with one player per line. Records are split across numbered files, followed by a completion marker so your pipeline can tell when the whole run is ready.
To bring events from your bucket into FirstLook, see S3 Events. To download the data behind an analytics chart, see Export Analytics.
Setting up your S3 bucket
Section titled “Setting up your S3 bucket”Create an IAM role in your AWS account that FirstLook can assume to write exports. The setup follows the same cross-account role pattern as S3 Events, with permissions to write files instead of read them.
The examples below use the prefix firstlook/exports. You can use another prefix, but the IAM policy and the dashboard configuration must match. For multiple games sharing a bucket, use a separate prefix for each game.
1. Create an IAM policy
Section titled “1. Create an IAM policy”Create a policy with the following permissions. Replace YOUR_BUCKET_NAME with your bucket name and change firstlook/exports if you chose a different prefix.
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "s3:PutObject", "Resource": "arn:aws:s3:::YOUR_BUCKET_NAME/firstlook/exports/*" }, { "Effect": "Allow", "Action": "s3:DeleteObject", "Resource": "arn:aws:s3:::YOUR_BUCKET_NAME/firstlook/exports/_firstlook_probe_*" } ]}s3:PutObject allows FirstLook to upload export files and the completion marker. The narrower s3:DeleteObject permission allows it to remove the temporary file written when you save the configuration. The exporter does not need to read or list your existing objects.
If you leave Prefix empty, change the write resource to arn:aws:s3:::YOUR_BUCKET_NAME/* and the probe cleanup resource to arn:aws:s3:::YOUR_BUCKET_NAME/_firstlook_probe_*.
If your bucket uses SSE-KMS encryption, also grant the role the required access to your KMS key in both its IAM policy and the key policy. See AWS’s PutObject permissions.
2. Create an IAM role with a trust policy
Section titled “2. Create an IAM role with a trust policy”Create an IAM role, such as FirstLookPlayerExport, and attach the policy above. Configure its trust policy to allow FirstLook’s AWS account to assume it with an External ID condition.
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::409257555035:root" }, "Action": "sts:AssumeRole", "Condition": { "StringEquals": { "sts:ExternalId": "YOUR_EXPORT_EXTERNAL_ID" } } } ]}The External ID identifies this export destination when FirstLook assumes the role. It helps prevent the confused deputy problem.
FirstLook generates the External ID when you first save the destination. Keep the placeholder in the trust policy for now, then replace it with the generated value in step 4.
3. Save an initial dashboard configuration
Section titled “3. Save an initial dashboard configuration”Open your game’s dashboard and go to Configuration > Player Data Export > Configuration.
Enter the following settings, keeping Enabled off until the role setup is complete:
| Setting | Value |
|---|---|
| Kind | Amazon S3. |
| Bucket | Your bucket name, without s3:// or a path. |
| Prefix | firstlook/exports, or the prefix you used in the IAM policy. Optional if the policy permits writing at the bucket root. |
| IAM Role ARN | Your role’s ARN, such as arn:aws:iam::123456789012:role/FirstLookPlayerExport. |
| AWS Region | The region where the bucket lives, such as us-east-1. |
| Chunk size | Players per file. The default is 1,000; the minimum is 1. |
| Enabled | Off during initial setup; on when you’re ready for automatic exports. |
Click Save Changes. FirstLook saves the destination, generates an External ID, and attempts a write probe even while Enabled is off.
Because the trust policy still contains the placeholder, the first save is expected to show an IAM role error. The destination is saved, and its read-only External ID field is now available.
4. Add the External ID and enable exports
Section titled “4. Add the External ID and enable exports”- Copy External ID from the Player Data Export Configuration tab.
- In your IAM role’s trust policy, replace
YOUR_EXPORT_EXTERNAL_IDwith that exact value. - Return to FirstLook, turn Enabled on, and click Save Changes again.
- Confirm that the dashboard reports Export destination saved and write probe passed.
Use the External ID from this export configuration, including if you already have S3 Events configured. Resaving the destination preserves its External ID. If you delete and recreate the destination, update the trust policy with its new External ID.
Saving validates access by writing a temporary _firstlook_probe_<uuid> object under the configured prefix, then attempting to delete it. Saving does not run a full player export; enabled destinations are picked up by subsequent export runs.
Export files
Section titled “Export files”Each run creates its own directory. With the example prefix above, the layout is:
s3://YOUR_BUCKET_NAME/firstlook/exports/ 2026-10-29/ 20261029T143012Z_<uuid>/ my-game_players_20261029T143012Z_0001.jsonl my-game_players_20261029T143012Z_0002.jsonl _SUCCESS- The date directory and run timestamp use UTC and reflect when that game’s export starts.
- Each attempt, including a retry, has a unique ID, so another attempt does not overwrite the earlier directory or reuse its completion marker.
- The date directory sits directly under your configured prefix; there is no extra game-slug directory.
- Part numbers start at
0001. Each file contains up to the configured chunk size; the final file can contain fewer players. - Files contain UTF-8 JSONL: one JSON object per line, with no surrounding JSON array.
_SUCCESSis a zero-byte S3 object written after all parts have uploaded successfully. A game with no players produces the marker with no JSONL parts.
Reading a completed run
Section titled “Reading a completed run”Wait for _SUCCESS before processing a run directory. Then read all .jsonl parts in that directory as one export. A directory without _SUCCESS may be incomplete and should not be loaded as a successful run.
Each run exports the full set of current records, rather than only records that changed since the previous run. If you retain multiple runs in your warehouse, keep their run IDs or dates separate, or merge records using player.game_id and player.id instead of appending every snapshot into one current-player table.
Player records are read in batches during the run. Values reflect when each batch is read; the run is not a transactionally consistent view of every player at one exact instant.
You control retention of objects in your bucket. Configure S3 lifecycle rules if you want older runs or incomplete directories to expire.
Personal information
Section titled “Personal information”Dedicated identity fields for email address, first name, and last name are omitted. However, exports retain platform identifiers, account names and handles, notes, custom data, and other fields that may contain personal information. Treat the exported records as player data rather than anonymous data.
Monitoring exports
Section titled “Monitoring exports”Go to Configuration > Player Data Export > Monitor to see:
- Last Run — When the most recent export attempt started.
- Last Success — When an export last completed successfully.
- Status —
Pending,Healthy, orFailed, based on the latest recorded success or error. - Last Error — The most recent recorded error and its time.
Before the first export attempt, Monitor shows that no export runs have occurred yet. The table summarizes the latest state; it is not a per-file log or a history of every run.
Troubleshooting
Section titled “Troubleshooting”| Symptom | What to check |
|---|---|
| Failed to assume IAM role | Check the Role ARN, FirstLook account principal, and sts:ExternalId condition. Use the External ID shown on the export Configuration tab. |
| Write probe failed | Check the bucket name, AWS Region, prefix, role’s s3:PutObject permissions, and any bucket or KMS policies that affect writes. |
| A probe file remains in the bucket | Check s3:DeleteObject permissions for _firstlook_probe_*. A failed cleanup does not by itself mean the write probe failed. |
Files exist but _SUCCESS is missing | Treat the directory as incomplete. Check Monitor for an error and wait for a successful run before loading it. |
| No files after saving | A save runs a write probe, not a full export. Check Enabled, resolve configuration errors, and check Monitor for the next export attempt. |
After changing an IAM or bucket policy, return to Configuration and click Save Changes to rerun the write probe. Check Monitor to confirm that a full export succeeds.