# Splitwise Data Extractor (`pramodkonde17/splitwise-data-extractor`) Actor

It fetches: User profile, all groups with member balances, all friends with balances, and all expenses (paginated automatically). Supports date filtering, group filtering, and a max-expenses cap

- **URL**: https://apify.com/pramodkonde17/splitwise-data-extractor.md
- **Developed by:** [Pramod Konde](https://apify.com/pramodkonde17) (community)
- **Categories:** Integrations, Travel
- **Stats:** 1 total users, 0 monthly users, 100.0% runs succeeded, NaN bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per usage

This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-usage

## What's an Apify Actor?

Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md):

```bash
npm install apify-client
```

In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md):

```bash
pip install apify-client
```

In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md):

````bash
# MacOS / Linux
curl -fsSL https://apify.com/install-cli.sh | bash
# Windows
irm https://apify.com/install-cli.ps1 | iex
```bash

In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md).

If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).


# README

## Splitwise Data Extractor

Extract your expenses, groups, friends, and account data from Splitwise using the official Splitwise API. All data is exported to Apify's dataset storage, ready for download as JSON, CSV, or Excel.

### What does this Actor do?

This Actor connects to your Splitwise account via the official OAuth 2.0 API and extracts:

| Data Type | What's included |
|---|---|
| **User** | Your profile, balances across currencies, notification settings |
| **Groups** | All groups you're in, member list, debts (original and simplified) |
| **Friends** | Your full friend list with per-friend balances in each currency |
| **Expenses** | All transactions — amounts, who paid, who owes what, categories, notes, receipts |

Results are saved to the Apify **Dataset** (download as JSON, CSV, or Excel) and a summary is saved to the **Key-Value Store** under `OUTPUT`.

---

### Getting your Splitwise Access Token

You need a Splitwise OAuth 2.0 Bearer token to use this Actor. Here's the quickest way to get one:

1. Go to **[https://secure.splitwise.com/apps/new](https://secure.splitwise.com/apps/new)** and register a new app (takes 1 minute — any name/URL works).
2. After creating the app, go to its settings page. You'll see a **Consumer Key** and **Consumer Secret**.
3. Use the OAuth 2.0 flow to get a Bearer token (or use the Splitwise API explorer at [dev.splitwise.com](https://dev.splitwise.com) to test and get a token for your own account).

> **Security note:** Your access token is treated as a secret by Apify and is never stored in run logs or visible to others. It only gives access to your own Splitwise account — it cannot access other users' accounts.

---

### Input

| Field | Type | Required | Description |
|---|---|---|---|
| `accessToken` | string | ✅ Yes | Your Splitwise OAuth 2.0 Bearer token |
| `dataToFetch` | array | No | Which data to fetch: `user`, `groups`, `friends`, `expenses`. Defaults to all four. |
| `datedAfter` | string | No | Only fetch expenses after this date (format: `YYYY-MM-DD`) |
| `datedBefore` | string | No | Only fetch expenses before this date (format: `YYYY-MM-DD`) |
| `groupId` | integer | No | Only fetch expenses from this group (find it in the group's URL on splitwise.com) |
| `maxExpenses` | integer | No | Maximum number of expenses to fetch. `0` means unlimited. |

#### Example input

```json
{
  "accessToken": "your-bearer-token-here",
  "dataToFetch": ["user", "groups", "friends", "expenses"],
  "datedAfter": "2024-01-01",
  "datedBefore": "2024-12-31",
  "maxExpenses": 500
}
````

***

### Output

All results are pushed to the **default Dataset**. Each record has a `_type` field indicating what kind of record it is (`user`, `group`, `friend`, or `expense`).

#### Example expense record

```json
{
  "_type": "expense",
  "id": 123456789,
  "group_id": 1234567,
  "description": "Dinner at Nobu",
  "payment": false,
  "cost": "120.00",
  "currency_code": "USD",
  "date": "2024-08-15T00:00:00Z",
  "category": {
    "id": 12,
    "name": "Dining out"
  },
  "users": [
    {
      "user_id": 111,
      "paid_share": "120.00",
      "owed_share": "60.00",
      "net_balance": "60.00"
    },
    {
      "user_id": 222,
      "paid_share": "0.00",
      "owed_share": "60.00",
      "net_balance": "-60.00"
    }
  ],
  "created_by": { "id": 111, "first_name": "Alice" },
  "created_at": "2024-08-15T14:32:00Z"
}
```

#### Example group record

```json
{
  "_type": "group",
  "id": 1234567,
  "name": "NYC Apartment",
  "group_type": "apartment",
  "members": [
    {
      "id": 111,
      "first_name": "Alice",
      "balance": [{ "currency": "USD", "amount": 250.00 }]
    }
  ],
  "simplified_debts": [
    { "from": 222, "to": 111, "amount": "250.00", "currency_code": "USD" }
  ]
}
```

#### Key-Value Store: OUTPUT

After the run completes, a summary is saved under the `OUTPUT` key:

```json
{
  "fetchedAt": "2024-08-15T14:32:00.000Z",
  "userId": 111,
  "userEmail": "alice@example.com",
  "userFullName": "Alice Smith",
  "defaultCurrency": "USD",
  "filters": {
    "datedAfter": "2024-01-01",
    "datedBefore": null,
    "groupId": null,
    "maxExpenses": null
  },
  "counts": {
    "user": 1,
    "groups": 5,
    "friends": 12,
    "expenses": 347
  }
}
```

***

### Use cases

- **Personal finance analysis** — Export all your expenses to Excel or Google Sheets for custom budgeting
- **Debt tracking** — Get a clear picture of who owes you what across all groups and friends
- **Data backup** — Archive your Splitwise history before closing your account
- **Accounting exports** — Feed Splitwise data into your own accounting tools
- **Household expense reports** — Summarize shared expenses for a specific group over a time period

***

### Rate limits & performance

Splitwise enforces conservative rate limits on their self-serve API. This Actor handles rate limit errors gracefully and will surface a clear message if limits are hit. For accounts with hundreds of expenses, the run typically completes in under 60 seconds.

Memory requirement: 128 MB minimum (very lightweight — no browser, no headless Chrome).

***

### Legal & compliance

This Actor uses the **official Splitwise REST API** (not web scraping) and requires the user to authenticate with their own account credentials via OAuth 2.0. It only accesses data that the authenticated user has permission to view.

> **Disclaimer:** This Actor is an unofficial integration and is not affiliated with, endorsed by, or supported by Splitwise Inc. Use of the Splitwise API is subject to the [Splitwise API Terms of Use](https://dev.splitwise.com/#section/Terms-of-Use).

***

### Support

If you encounter any issues, please open a GitHub issue or contact via the Apify Actor Issues tab.

# Actor input Schema

## `accessToken` (type: `string`):

Your Splitwise OAuth 2.0 Bearer token. Register your app at https://secure.splitwise.com/apps/new to get your consumer key and secret, then complete the OAuth flow to get a token. You can also find a quick access token in your app settings at dev.splitwise.com.

## `dataToFetch` (type: `array`):

Select which types of data to extract from your Splitwise account. Defaults to fetching everything.

## `datedAfter` (type: `string`):

Only fetch expenses on or after this date. Format: YYYY-MM-DD (e.g. 2024-01-01). Leave empty to fetch from the beginning of time.

## `datedBefore` (type: `string`):

Only fetch expenses on or before this date. Format: YYYY-MM-DD (e.g. 2024-12-31). Leave empty to fetch up to today.

## `groupId` (type: `integer`):

Only fetch expenses from this specific Splitwise group. You can find the Group ID in the URL when viewing a group (e.g. splitwise.com/groups/12345). Leave empty to fetch expenses from all groups.

## `maxExpenses` (type: `integer`):

Maximum number of expenses to retrieve. Set to 0 to fetch all expenses (may take longer for accounts with many expenses).

## Actor input object example

```json
{
  "dataToFetch": [
    "user",
    "groups",
    "friends",
    "expenses"
  ],
  "maxExpenses": 0
}
```

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {};

// Run the Actor and wait for it to finish
const run = await client.actor("pramodkonde17/splitwise-data-extractor").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {}

# Run the Actor and wait for it to finish
run = client.actor("pramodkonde17/splitwise-data-extractor").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{}' |
apify call pramodkonde17/splitwise-data-extractor --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=pramodkonde17/splitwise-data-extractor",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "Splitwise Data Extractor",
        "description": "It fetches: User profile, all groups with member balances, all friends with balances, and all expenses (paginated automatically). Supports date filtering, group filtering, and a max-expenses cap",
        "version": "0.1",
        "x-build-id": "L1B3xKh7EP1rwGGjQ"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/pramodkonde17~splitwise-data-extractor/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-pramodkonde17-splitwise-data-extractor",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/acts/pramodkonde17~splitwise-data-extractor/runs": {
            "post": {
                "operationId": "runs-sync-pramodkonde17-splitwise-data-extractor",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor and returns information about the initiated run in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/runsResponseSchema"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/acts/pramodkonde17~splitwise-data-extractor/run-sync": {
            "post": {
                "operationId": "run-sync-pramodkonde17-splitwise-data-extractor",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "inputSchema": {
                "type": "object",
                "required": [
                    "accessToken"
                ],
                "properties": {
                    "accessToken": {
                        "title": "Splitwise Access Token",
                        "type": "string",
                        "description": "Your Splitwise OAuth 2.0 Bearer token. Register your app at https://secure.splitwise.com/apps/new to get your consumer key and secret, then complete the OAuth flow to get a token. You can also find a quick access token in your app settings at dev.splitwise.com."
                    },
                    "dataToFetch": {
                        "title": "Data to Fetch",
                        "type": "array",
                        "description": "Select which types of data to extract from your Splitwise account. Defaults to fetching everything.",
                        "items": {
                            "type": "string",
                            "enum": [
                                "user",
                                "groups",
                                "friends",
                                "expenses"
                            ]
                        },
                        "default": [
                            "user",
                            "groups",
                            "friends",
                            "expenses"
                        ]
                    },
                    "datedAfter": {
                        "title": "Expenses: From Date",
                        "pattern": "^(\\d{4}-\\d{2}-\\d{2})?$",
                        "type": "string",
                        "description": "Only fetch expenses on or after this date. Format: YYYY-MM-DD (e.g. 2024-01-01). Leave empty to fetch from the beginning of time."
                    },
                    "datedBefore": {
                        "title": "Expenses: To Date",
                        "pattern": "^(\\d{4}-\\d{2}-\\d{2})?$",
                        "type": "string",
                        "description": "Only fetch expenses on or before this date. Format: YYYY-MM-DD (e.g. 2024-12-31). Leave empty to fetch up to today."
                    },
                    "groupId": {
                        "title": "Expenses: Filter by Group ID",
                        "minimum": 1,
                        "type": "integer",
                        "description": "Only fetch expenses from this specific Splitwise group. You can find the Group ID in the URL when viewing a group (e.g. splitwise.com/groups/12345). Leave empty to fetch expenses from all groups."
                    },
                    "maxExpenses": {
                        "title": "Max Expenses to Fetch",
                        "minimum": 0,
                        "type": "integer",
                        "description": "Maximum number of expenses to retrieve. Set to 0 to fetch all expenses (may take longer for accounts with many expenses).",
                        "default": 0
                    }
                }
            },
            "runsResponseSchema": {
                "type": "object",
                "properties": {
                    "data": {
                        "type": "object",
                        "properties": {
                            "id": {
                                "type": "string"
                            },
                            "actId": {
                                "type": "string"
                            },
                            "userId": {
                                "type": "string"
                            },
                            "startedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "finishedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "status": {
                                "type": "string",
                                "example": "READY"
                            },
                            "meta": {
                                "type": "object",
                                "properties": {
                                    "origin": {
                                        "type": "string",
                                        "example": "API"
                                    },
                                    "userAgent": {
                                        "type": "string"
                                    }
                                }
                            },
                            "stats": {
                                "type": "object",
                                "properties": {
                                    "inputBodyLen": {
                                        "type": "integer",
                                        "example": 2000
                                    },
                                    "rebootCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "restartCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "resurrectCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "computeUnits": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "options": {
                                "type": "object",
                                "properties": {
                                    "build": {
                                        "type": "string",
                                        "example": "latest"
                                    },
                                    "timeoutSecs": {
                                        "type": "integer",
                                        "example": 300
                                    },
                                    "memoryMbytes": {
                                        "type": "integer",
                                        "example": 1024
                                    },
                                    "diskMbytes": {
                                        "type": "integer",
                                        "example": 2048
                                    }
                                }
                            },
                            "buildId": {
                                "type": "string"
                            },
                            "defaultKeyValueStoreId": {
                                "type": "string"
                            },
                            "defaultDatasetId": {
                                "type": "string"
                            },
                            "defaultRequestQueueId": {
                                "type": "string"
                            },
                            "buildNumber": {
                                "type": "string",
                                "example": "1.0.0"
                            },
                            "containerUrl": {
                                "type": "string"
                            },
                            "usage": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "integer",
                                        "example": 1
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "usageTotalUsd": {
                                "type": "number",
                                "example": 0.00005
                            },
                            "usageUsd": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "number",
                                        "example": 0.00005
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```