API Documentation

Complete guide to integrating secure code execution into your application.

Quick Start

Execute code in two simple steps:

  1. Submit your code to get a job ID
  2. Poll the status endpoint until execution completes

Authentication

All API requests require authentication using your API key in the X-API-KEY header.

💡 Get your API key from the Dashboard

Submit Code

POST/api/v1/runner/submit

Request Body

{
  "code": "print('Hello, World!')",
  "language": "python",
  "input": ""
}

Supported languages: python, javascript, cpp, java

Response

{
  "success": true,
  "data": {
    "jobId": "694736e4b1f2f3fedab4d30f",
    "status": "queued"
  }
}

Get Status

GET/api/v1/runner/{jobId}/result

Response

{
    "code": 200,
    "success": true,
    "message": "job result fetched successfully",
    "data": {
        "jobId": "695bd82641bcbdea08ee3fbc",
        "status": "success",
        "language": "cpp",
        "stdout": "Hello Neuron",
        "stderr": "",
        "executionTimeMs": 802,
        "queueTimeMs": 132,
        "totalTimeMs": 934,
        "exitCode": 0,
        "sandboxErrorType": null,
        "sandboxErrorMessage": "",
        "queuedAt": "2026-01-05T15:26:30.796Z",
        "startedAt": "2026-01-05T15:26:30.928Z",
        "finishedAt": "2026-01-05T15:26:31.73Z"
    }
}

Poll every 1 second until status is "queued" or "running"

Response Fields

FieldTypeDescription
jobIdstringUnique identifier for the job
statusstringqueued, running, success, failed
stdoutstringStandard output from execution
stderrstringStandard error output
executionTimeMsnumberExecution time in milliseconds
queueTimeMsnumberTime spent in queue in milliseconds
totalTimeMsnumberTotal time (queue + execution) in milliseconds
exitCodenumberProcess exit code (0 for success)
sandboxErrorTypestring | nullError type if failed (TLE, MLE, etc.)
sandboxErrorMessagestringError message if failed
queuedAtstringISO timestamp when job was queued
startedAtstringISO timestamp when execution started
finishedAtstringISO timestamp when execution finished

Generating API Keys

  1. Sign in to your account
  2. Navigate to the Dashboard
  3. Click "Generate API Key"
  4. Copy and securely store your key (format: nr_live_...)
⚠️ You can only have one active API key at a time. Generating a new key will revoke the previous one.

Securing Credentials

  • •Never commit API keys to version control
  • •Use environment variables (process.env.NEURON_API_KEY)
  • •Rotate keys regularly
  • •Use server-side API calls only

Rate Limits

To ensure fair usage and system stability, we enforce rate limits on API endpoints:

  • Authentication Routes: 10 requests/minute
  • Code Submission: 60 requests/minute
Exceeding rate limits will result in 429 Too Many Requests errors

How Credits Work

Each successful code execution costs 1 credit.

Only successful executions (status = "success") consume credits. Failed runs are free.

Fair Billing Policy

You won't be charged for:

  • Time Limit Exceeded (TLE)
  • Memory Limit Exceeded (MLE)
  • Compilation errors
  • Runtime errors

Free Credits

200 Free Credits

Every new account starts with 200 free credits (100 normally, 200 for early users)

  • No credit card required to start
  • Perfect for testing and small projects
  • View remaining balance in Dashboard
  • Credits never expire during beta

Code Limitations

All code executions run in isolated Docker containers with these limits:

  • Execution Time: 3 seconds maximum
  • Memory: 256MB maximum
  • Network Access: Disabled for security

Error Types

Error TypeDescriptionCharged?
TLETime Limit Exceeded: the program ran longer than allowedNo
MLEMemory Limit Exceeded: the program used more memory than allowedNo
CompilationErrorCompilation failed. See error detailsNo
RuntimeErrorRuntime Error: the program crashed during executionNo
SandboxErrorSandbox Error: execution environment failedNo
InternalErrorInternal Error: something went wrong on the serverNo

Troubleshooting

Invalid API Key Error

Check that:

  • Your API key starts with nr_live_
  • You're using the X-API-KEY header
  • The key hasn't been revoked

Code Takes Too Long

  • Optimize your code for efficiency
  • Avoid infinite loops
  • Time limit is 3 seconds per execution

Dashboard

Track all your API activity:

  • View execution history
  • Monitor credit usage and balance
  • See execution times and success rates
  • Filter by language, status, date
Go to Dashboard

Complete Example

// Submit code
const res = await fetch('https://api.neuron-labs.xyz/api/v1/runner/submit', {
  method: 'POST',
  headers: {
    'X-API-KEY': 'nr_live_...',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    code: 'print("Hello")',
    language: 'python',
    input: ''
  })
});

const { data: { jobId } } = await res.json();

// Poll for results
const poll = async () => {
  const statusRes = await fetch(
    `https://api.neuron-labs.xyz/api/v1/runner/${jobId}/result`,
    { headers: { 'X-API-KEY': 'nr_live_...' } }
  );
  
  const { data } = await statusRes.json();
  
  if (data.status === 'queued' || data.status === 'running') {
    setTimeout(poll, 1000);
  } else {
    console.log('Output:', data.stdout);
  }
};

poll();

Best Practices

  • ✓Always use HTTPS in production
  • ✓Store API keys in environment variables
  • ✓Make API calls from backend only
  • ✓Implement rate limiting
  • ✓Validate user input before sending
  • ✓Handle errors gracefully

Need Help?

Try our playground or reach out for support.

Try PlaygroundContact Support