RecoupGet a free auditFree audit

API REFERENCE

Create measurement job

On this page
POST/api/research/measurement-jobs

One async ingest resource. source:"current" captures present counts via the snapshot pipeline. Provide exactly one of catalog_id / album_ids / isrcs in scope. The returned id is a snapshot id you can pass to Create catalog to materialize the measured tracks into an account-owned catalog.

Authentication

See the authentication guide for API key and account access requirements.

Request

cURL
curl --request POST \
  --url 'https://api.recoupable.dev/api/research/measurement-jobs' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": {
    "catalog_id": "YOUR_ID",
    "album_ids": [
      "string"
    ],
    "isrcs": [
      "string"
    ]
  },
  "source": "current"
}'

Try it

Fill in the fields, send the request from your browser, and read the live response. The curl below updates as you type.

Kept in this browser tab only and cleared when it closes.

cURL for this request
curl --request POST \
  --url 'https://recoup-api.vercel.app/api/research/measurement-jobs' \
  --header 'Content-Type: application/json' \
  --data '{
  "scope": {
    "catalog_id": "YOUR_ID",
    "album_ids": [
      "string"
    ],
    "isrcs": [
      "string"
    ]
  },
  "source": "current"
}'

Request body required

application/json

scopeobjectrequired

Provide exactly one of catalog_id, album_ids, or isrcs.

Properties for scope
catalog_idstring

format: uuid

album_idsarray<string>
Item properties for album_ids

string

isrcsarray<string>
Item properties for isrcs

string

sourcestring · enumrequired

current = capture present counts (Apify snapshot).

Values: "current"

platformsarray<string>

Default: ["spotify"]

Item properties for platforms

string

Responses

202Job accepted.

application/json

statusstring
sourcestring
idstring

Snapshot id.

format: uuid

statestring · enum

Values: "queued"

album_countinteger

Albums the job will capture.

estimated_cost_usdnumber

Scraper cost estimate before spend.

400Validation error — provide a source and exactly one of scope.catalog_id, scope.album_ids, scope.isrcs.

application/json

statusstring · enumrequired

Values: "error"

errorstringrequired

Human-readable error message describing what went wrong.

401Authentication failed — invalid or missing API key.

application/json

statusstring · enumrequired

Values: "error"

errorstringrequired

Human-readable error message describing what went wrong.

429Per-organization monthly cap reached.

application/json

statusstring · enumrequired

Values: "error"

errorstringrequired

Human-readable error message describing what went wrong.

Full specification

Download the OpenAPI file for complete schemas, constraints, and examples.

Download research.json
View operation source
json
{
  "summary": "Create a measurement job",
  "description": "One async ingest resource. `source:\"current\"` captures present counts via the snapshot pipeline. Provide exactly one of `catalog_id` / `album_ids` / `isrcs` in `scope`. The returned `id` is a snapshot id you can pass to [Create catalog](/api-reference/songs/catalogs-create) to materialize the measured tracks into an account-owned catalog.",
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ResearchMeasurementJobRequest"
        }
      }
    }
  },
  "responses": {
    "202": {
      "description": "Job accepted.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ResearchMeasurementJobResponse"
          }
        }
      }
    },
    "400": {
      "description": "Validation error — provide a `source` and exactly one of `scope.catalog_id`, `scope.album_ids`, `scope.isrcs`.",
      "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"
          }
        }
      }
    },
    "429": {
      "description": "Per-organization monthly cap reached.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ResearchErrorResponse"
          }
        }
      }
    }
  }
}