Skip to main content
POST
/
api
/
external
/
v1
/
search
POST /search
curl --request POST \
  --url https://api.trackyard.com/api/external/v1/search
{
  "tracks": [
    {
      "id": "<string>",
      "title": "<string>",
      "artist": "<string>",
      "duration_seconds": 123,
      "bpm": 123,
      "key": "<string>",
      "genre": "<string>",
      "subgenres": [
        {}
      ],
      "moods": [
        {}
      ],
      "has_vocals": true,
      "energy_level": "<string>",
      "instruments": [
        {}
      ],
      "preview_url": "<string>"
    }
  ],
  "credits_remaining": 123
}
Search the Trackyard catalog using natural language queries. Describe what you need in plain English, and the AI infers genre, mood, BPM, instrumentation, and more. Cost: 1 credit per request

​
Authentication

All requests require a valid API key in the Authorization header: 
Authorization: Bearer your_api_key_here

​
Request Body

​
query
string
required
Natural language description of the music you need.Examples:
  • "upbeat electronic music for a tech startup video"
  • "moody piano for a rainy scene"
  • "15-second clip for an Instagram Reel about travel"
​
limit
number
default:20
Maximum number of results to return.Range: 1-100
​
offset
number
default:0
Pagination offset. Use with limit to paginate through results.
​
filters
object
Optional structured filters to refine results.

​
Example Request

curl -X POST https://api.trackyard.com/api/external/v1/search \
  -H "Authorization: Bearer $TRACKYARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "upbeat electronic music for tech startup video",
    "limit": 5,
    "filters": {
      "has_vocals": false,
      "min_bpm": 120,
      "max_bpm": 140
    }
  }'

​
Response

​
tracks
array
required
Array of track objects matching your query.
​
credits_remaining
number
required
Your remaining credit balance after this request.

​
Example Response

{
  "tracks": [
    {
      "id": "trk_abc123",
      "title": "Digital Sunrise",
      "artist": "Sync Lab",
      "duration_seconds": 142,
      "bpm": 128,
      "key": "C Major",
      "genre": "Electronic",
      "subgenres": ["Deep House", "Tech House"],
      "moods": ["Upbeat", "Energetic", "Modern"],
      "has_vocals": false,
      "energy_level": "high",
      "instruments": ["Synth", "Electronic Drums", "Bass"],
      "preview_url": "https://cdn.trackyard.com/previews/trk_abc123.mp3"
    },
    {
      "id": "trk_def456",
      "title": "Innovation Drive",
      "artist": "The Production House",
      "duration_seconds": 156,
      "bpm": 132,
      "key": "D Major",
      "genre": "Pop",
      "subgenres": ["Dance-Pop", "Electropop"],
      "moods": ["Upbeat", "Motivational", "Tech"],
      "has_vocals": false,
      "energy_level": "high",
      "instruments": ["Synth", "Piano", "Drums"],
      "preview_url": "https://cdn.trackyard.com/previews/trk_def456.mp3"
    }
  ],
  "credits_remaining": 487
}

​
Rate Limits

All responses include rate limit headers: 
X-RateLimit-Limit: 5
X-RateLimit-Remaining: 3
X-RateLimit-Limit-Daily: 50
X-RateLimit-Remaining-Daily: 42
X-Credits-Remaining: 44
See Rate Limits & Credits for details.

​
Error Responses

​
401 Unauthorized
Missing or invalid API key.
{
  "error": "Unauthorized",
  "message": "Invalid API key"
}
​
402 Payment Required
Out of credits.
{
  "error": "Out of credits",
  "message": "Please top up or upgrade your plan"
}
​
429 Too Many Requests
Rate limit exceeded.
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded"
}
See Error Codes for full reference.

​
Tips for Better Results

Be specific: “upbeat electronic music for a tech startup video” beats “upbeat music”
Include context: Describe the scene, use case, or platform (Instagram Reel, podcast intro, etc.)
Combine AI + filters: Let the AI interpret your query, then add filters for surgical precision
Preview before downloading: Stream the preview_url to audition tracks before spending a credit on /download-track

​
Next Steps

Download Track

Download full tracks or smart-trimmed clips

Parameters Guide

Full reference of all search filters

AI-Powered Search

Learn how natural language search works

Code Examples

Python and JavaScript examples