Python Quick Start

Search art metadata, handle pagination, and manage errors from Python using the requests library.

Prerequisites

Python 3.8 or later and pip.

Install requests

pip install requests

Search by tag

Find posts by an exact tag name using the tag parameter.

import requests

response = requests.get("https://lagoon.io/api/v1/search", params={
    "tag": "blue_hair",
    "limit": 10
})
data = response.json()

if data["ok"]:
    for post in data["results"]:
        print(f"{post['title']} by {post['artist_handle']}")
        print(f"  Platform: {post['platform_name']}")
        print(f"  Tags: {', '.join(post['tags'][:5])}")
        print()

Each post in results includes id, source_url, title, posted_at, platform, platform_name, artist_handle, artist_name, deleted, and tags.

Natural language search

Pass freeform text to the nl parameter. The API extracts platform, artist, date range, tags, and sort order from your query. The response includes a filters key showing what was parsed.

response = requests.get("https://lagoon.io/api/v1/search", params={
    "nl": "solo girl on pixiv from 2025"
})
data = response.json()

# See what the parser extracted
print("Parsed filters:", data.get("filters", {}))
# {'platform': 'pixiv', 'from': '2025-01-01', 'to': '2025-12-31', 'tags': ['1girl'], 'sfw': True}

for post in data["results"]:
    print(post["title"])

Look up an artist

Query a handle to get all linked accounts across platforms.

response = requests.get("https://lagoon.io/api/v1/artist", params={
    "handle": "hews__"
})
data = response.json()

if data["ok"]:
    artist = data["artist"]
    print(f"{artist['display_name']} ({artist['post_count']} posts)")
    for p in artist["platforms"]:
        print(f"  {p['platform_name']}: {p['handle']}")
        if p["profile_url"]:
            print(f"    {p['profile_url']}")

Authenticate with an API key

Unauthenticated requests are rate-limited to 30 per minute. To use a higher-limit tier, pass your key in the X-API-Key header.

API_KEY = "lg_your_key_here"

response = requests.get("https://lagoon.io/api/v1/search",
    params={"tag": "blue_hair", "limit": 20},
    headers={"X-API-Key": API_KEY}
)

Paginate through results

Use limit and offset to page through results. When the response count is less than your limit, you have reached the last page.

def search_all(params):
    """Fetch all pages for a search query."""
    results = []
    offset = 0
    limit = params.get("limit", 50)

    while True:
        params["offset"] = offset
        resp = requests.get("https://lagoon.io/api/v1/search", params=params)
        data = resp.json()

        if not data["ok"]:
            break

        results.extend(data["results"])

        if data["count"] < limit:
            break

        offset += limit

    return results

# Fetch all blue_hair posts from X
all_posts = search_all({
    "tag": "blue_hair",
    "platform": "x",
    "limit": 100
})
print(f"Total: {len(all_posts)} posts")

Handle errors

The API returns "ok": false with an error message on failure. Check the HTTP status code for specific error types.

import time

def safe_search(params, api_key=None):
    headers = {}
    if api_key:
        headers["X-API-Key"] = api_key

    resp = requests.get("https://lagoon.io/api/v1/search",
        params=params, headers=headers)

    if resp.status_code == 429:
        retry = int(resp.headers.get("Retry-After", 60))
        print(f"Rate limited. Waiting {retry}s...")
        time.sleep(retry)
        return safe_search(params, api_key)

    if resp.status_code == 402:
        raise Exception("Insufficient balance. Add funds at lagoon.io/dashboard.")

    if resp.status_code == 401:
        raise Exception("Invalid or expired API key.")

    data = resp.json()
    if not data["ok"]:
        raise Exception(data.get("error", "Unknown error"))

    return data

Full example

A complete script that searches for recent art by an artist and prints the results.

import requests

BASE = "https://lagoon.io/api/v1"

# Step 1: Look up the artist
artist_resp = requests.get(f"{BASE}/artist", params={"handle": "hews__"})
artist_data = artist_resp.json()

if artist_data["ok"]:
    artist = artist_data["artist"]
    print(f"{artist['display_name']} - {artist['post_count']} indexed posts")
    for p in artist["platforms"]:
        print(f"  {p['platform_name']}: {p['handle']}")
    print()

# Step 2: Get their recent posts
search_resp = requests.get(f"{BASE}/search", params={
    "artist": "hews__",
    "limit": 5
})
search_data = search_resp.json()

if search_data["ok"]:
    for post in search_data["results"]:
        print(f"{post['title']}")
        print(f"  {post['platform_name']} | {post['posted_at'][:10]}")
        tags = [t for t in post["tags"] if not t.startswith("rating:")]
        print(f"  Tags: {', '.join(tags[:8])}")
        if post["source_url"]:
            print(f"  {post['source_url']}")
        print()

Next steps

API documentation for the full endpoint reference.
Natural language search for everything the NL parser recognizes.
Rate limits and pricing for each tier.