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"
}'

Request body required

application/json

scopeobjectrequired

Provide exactly one of catalog_id, album_ids, or isrcs.

Properties

catalog_idstring

format: uuid

album_idsarray<string>

Item properties

string

isrcsarray<string>

Item properties

string

sourcestring · enumrequired

current = capture present counts (Apify snapshot).

Values: "current"

platformsarray<string>

Default: ["spotify"]

Item properties

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"
          }
        }
      }
    }
  }
}