# Track

Source: https://recoupable.dev/docs/api-reference/research/track

Read track details using the `id` selected from [Search](/docs/api-reference/research/search) with `type=tracks`. Treat this ID as an opaque string, separate from a Recoup account UUID. Track metadata and available fields vary by recording.

## GET /api/research/track

Full OpenAPI specification: https://recoupable.dev/docs/spec/research.json

## Authentication

The supplied specification does not declare an OpenAPI security object for this operation. Its declared headers and parameters still apply. Consult the authentication guide and the full specification before calling it.

[Authentication guide](https://recoupable.dev/docs/authentication)

## Operation and referenced schemas

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Recoup API - Research",
    "description": "API documentation for the Recoup platform - an AI agent platform for the music industry",
    "license": {
      "name": "MIT"
    },
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://api.recoupable.dev"
    }
  ],
  "paths": {
    "/api/research/track": {
      "get": {
        "description": "Read track details using the `id` selected from [Search](/docs/api-reference/research/search) with `type=tracks`. Treat this ID as an opaque string, separate from a Recoup account UUID. Track metadata and available fields vary by recording.\n\nUse your Recoup API key (`x-api-key`) or supported bearer credential. Successful artist and track research reads cost $0.05 (50,000 micro-dollar credits). Recoup manages the data connections. Coverage and rate limits vary; see [Research availability](/docs/research-availability).",
        "parameters": [
          {
            "name": "id",
            "in": "query",
            "required": true,
            "description": "Provider track ID. Obtain it from search results or a track lookup.",
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$",
              "example": "track_123"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Track metadata",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResearchTrackResponse"
                }
              }
            }
          },
          "400": {
            "description": "Missing id or invalid provider ID string pattern.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResearchErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Authentication failed — invalid or missing API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResearchErrorResponse"
                }
              }
            }
          },
          "402": {
            "description": "Insufficient research credits. The response includes a static billingUrl; no checkout session is created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResearchInsufficientCreditsResponse"
                }
              }
            }
          },
          "403": {
            "description": "Credential, account or provider permission denied.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResearchErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Artist/track resolution or requested provider data was not found. A failed name search may be reported as 404; retry with an exact provider ID when known.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResearchErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Provider rate or quota limit. The adapter returns an error status but does not forward provider Retry-After headers. Avoid an unbounded retry loop.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResearchErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Missing provider configuration, transport failure or internal error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResearchErrorResponse"
                }
              }
            }
          },
          "501": {
            "$ref": "#/components/responses/ResearchDataSourceUnsupported"
          },
          "502": {
            "description": "Upstream provider failed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResearchErrorResponse"
                }
              }
            }
          },
          "504": {
            "description": "the configured research data connection request timed out.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResearchErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ResearchTrackResponse": {
        "type": "object",
        "description": "Track metadata and audio analysis.",
        "properties": {
          "status": {
            "type": "string",
            "example": "success"
          },
          "result": {
            "type": "string",
            "example": "success"
          },
          "message": {
            "type": "string",
            "example": "Data Retrieved."
          },
          "track_info": {
            "$ref": "#/components/schemas/ResearchTrackInfo"
          },
          "audio_analysis": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ResearchAudioAnalysisEntry"
            }
          }
        },
        "additionalProperties": true
      },
      "ResearchErrorResponse": {
        "type": "object",
        "required": [
          "status",
          "error"
        ],
        "description": "Error response returned by all research endpoints for validation failures (400) and authentication errors (401).",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "error"
            ],
            "example": "error"
          },
          "error": {
            "type": "string",
            "description": "Human-readable error message describing what went wrong.",
            "example": "Missing required parameter: artist"
          }
        }
      },
      "ResearchInsufficientCreditsResponse": {
        "type": "object",
        "description": "Returned (402) when the account lacks research credits. Nothing is charged and no Stripe object is created. Credits must be bought explicitly via [`POST /api/credits/sessions`](/docs/api-reference/credits/sessions-create).",
        "properties": {
          "error": {
            "type": "string",
            "enum": [
              "insufficient_credits"
            ]
          },
          "remaining_credits": {
            "type": "integer",
            "example": 0
          },
          "required_credits": {
            "type": "integer",
            "example": 50000
          },
          "billingUrl": {
            "type": "string",
            "description": "Static link to the Recoup app, where a human can save a card and buy credits. It is a constant, not a freshly minted Stripe Checkout Session, so a credit-gated endpoint that keeps returning 402 creates nothing. To buy credits programmatically, call [`POST /api/credits/sessions`](/docs/api-reference/credits/sessions-create).",
            "example": "https://app.recoupable.dev"
          }
        },
        "required": [
          "error",
          "remaining_credits",
          "required_credits",
          "billingUrl"
        ]
      },
      "ResearchTrackInfo": {
        "type": "object",
        "description": "Full track record.",
        "properties": {
          "title": {
            "type": "string"
          },
          "avatar": {
            "type": "string"
          },
          "site_url": {
            "type": "string"
          },
          "release_date": {
            "type": "string",
            "nullable": true
          },
          "artists": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ResearchArtistMini"
            }
          },
          "is_remix": {
            "type": "boolean"
          },
          "collaborators": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ResearchCollaborator"
            }
          },
          "labels": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          },
          "distributors": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                }
              },
              "additionalProperties": true
            }
          },
          "genres": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "links": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ResearchLink"
            }
          }
        },
        "additionalProperties": true
      },
      "ResearchAudioAnalysisEntry": {
        "type": "object",
        "properties": {
          "key": {
            "type": "string",
            "description": "Audio feature name, e.g. `acousticness`, `tempo`."
          },
          "value": {
            "type": "string",
            "description": "Feature value (string-encoded)."
          }
        }
      },
      "ResearchArtistMini": {
        "type": "object",
        "description": "Minimal artist reference embedded in catalog/activity payloads.",
        "properties": {
          "name": {
            "type": "string"
          }
        },
        "additionalProperties": true
      },
      "ResearchCollaborator": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "roles": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "additionalProperties": true
      },
      "ResearchLink": {
        "type": "object",
        "description": "External platform link.",
        "properties": {
          "source": {
            "type": "string",
            "description": "Platform name, e.g. `spotify`, `apple_music`."
          },
          "external_id": {
            "type": "string",
            "description": "Platform-specific ID."
          },
          "url": {
            "type": "string"
          },
          "isrc": {
            "type": "string",
            "description": "ISRC (tracks only)."
          }
        },
        "additionalProperties": true
      }
    },
    "responses": {
      "ResearchDataSourceUnsupported": {
        "description": "The configured research data source does not support this endpoint or data shape.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ResearchErrorResponse"
            },
            "example": {
              "status": "error",
              "error": "Request failed with status 501"
            }
          }
        }
      }
    }
  }
}
```