Quick start Get started with KaggleIngest in three simple steps: create an account, get your API key, and make your first request.
Overview KaggleIngest provides a simple REST API for accessing token-optimized Kaggle competition context. You’ll need an API key to authenticate your requests.
Create an account
Sign up to receive your API key and 10 free credits. curl -X POST https://api.kaggleingest.com/api/auth/signup \ -H "Content-Type: application/json" \ -d '{ "email": "[email protected] ", "password": "securepassword123" }'
Response: { "message" : "Account created successfully" , "api_key" : "ki_1a2b3c4d5e6f7g8h9i0j" , "instructions" : "Add 'X-API-Key: <your_key>' header to all API requests" }
Save your API key securely. You’ll need it for all subsequent requests. API keys start with the ki_ prefix.
Set your API key
Store your API key as an environment variable for easy access. export KAGGLEINGEST_API_KEY = "ki_1a2b3c4d5e6f7g8h9i0j"
Or save it in your shell profile (.bashrc, .zshrc, etc.): echo 'export KAGGLEINGEST_API_KEY="ki_1a2b3c4d5e6f7g8h9i0j"' >> ~/.zshrc source ~/.zshrc
Make your first request
Search for competitions or get competition context. Search competitions Find competitions by name or keyword: curl "https://api.kaggleingest.com/api/search?query=titanic" \ -H "X-API-Key: $KAGGLEINGEST_API_KEY "
Get competition context Retrieve token-optimized context for a specific competition: curl "https://api.kaggleingest.com/api/competitions/titanic" \ -H "X-API-Key: $KAGGLEINGEST_API_KEY "
First-time requests for a competition may return "status": "processing". The system fetches and caches the data in the background. Check back in 30-60 seconds for the complete context.
Understanding the response KaggleIngest returns data in TOON (Token-Oriented Object Notation) format, optimized for LLM consumption.
Processing response When a competition isn’t cached yet:
{ "slug" : "titanic" , "title" : "Processing..." , "status" : "processing" , "message" : "Metadata is being fetched. Check back in 60 seconds." }
Completed response Once processed, you’ll receive the full context:
{ "slug" : "titanic" , "title" : "Titanic - Machine Learning from Disaster" , "status" : "completed" , "formatted_output" : "=== COMPETITION: titanic === \n url: https://kaggle.com/c/titanic \n category: Getting Started \n prize: Knowledge \n\n === SCHEMA === \n ..." , "metadata" : { "url" : "https://kaggle.com/c/titanic" , "category" : "Getting Started" , "notebooks_count" : 3 } }
Next steps
API reference Explore all available endpoints and parameters
Search competitions Learn how to search for Kaggle competitions
Check your credits Monitor your usage and remaining credits
TOON format guide Learn how to interpret TOON-formatted responses
Example: Python integration Here’s a complete example using the requests library:
import requests import os API_KEY = os.getenv( "KAGGLEINGEST_API_KEY" ) BASE_URL = "https://api.kaggleingest.com/api" def get_competition_context ( slug : str ): """Fetch token-optimized context for a Kaggle competition.""" headers = { "X-API-Key" : API_KEY } response = requests.get( f " { BASE_URL } /competitions/ { slug } " , headers = headers) data = response.json() if data[ "status" ] == "processing" : print ( f "⏳ { data[ 'message' ] } " ) return None return data[ "formatted_output" ] # Usage context = get_competition_context( "titanic" ) if context: print (context)
Never commit your API key to version control. Use environment variables or a secrets manager.
Rate limits The free tier includes:
10 credits per account20 requests per minute rate limitSearch : No credit cost (rate-limited only)Competition context : 1 credit per request
Check your remaining credits:
curl "https://api.kaggleingest.com/api/auth/me" \ -H "X-API-Key: $KAGGLEINGEST_API_KEY "
Response:
{ "email" : "[email protected] " , "tier" : "free" , "credits" : 7 , "created_at" : "2026-03-03T10:15:30Z" }
Troubleshooting 401 Unauthorized Your API key is missing or invalid. Verify you’re sending the X-API-Key header.
429 Too Many Requests You’ve exceeded the rate limit (20 requests/minute). Wait a moment and retry.
402 Payment Required You’ve exhausted your free credits. Contact support for additional credits or upgrade options.
Status remains “processing” Some competitions take longer to fetch, especially those with many notebooks. Wait 1-2 minutes and retry. If the issue persists, the competition may be private or inaccessible.