# Create measurement job

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

Create a measurement job

## POST /api/research/measurement-jobs

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/measurement-jobs": {
      "post": {
        "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"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ResearchMeasurementJobRequest": {
        "type": "object",
        "required": [
          "scope",
          "source"
        ],
        "properties": {
          "scope": {
            "$ref": "#/components/schemas/ResearchMeasurementJobScope"
          },
          "source": {
            "type": "string",
            "enum": [
              "current"
            ],
            "description": "`current` = capture present counts (Apify snapshot)."
          },
          "platforms": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "default": [
              "spotify"
            ],
            "example": [
              "spotify"
            ]
          }
        }
      },
      "ResearchMeasurementJobResponse": {
        "type": "object",
        "description": "`id` is the snapshot id to poll.",
        "properties": {
          "status": {
            "type": "string",
            "example": "success"
          },
          "source": {
            "type": "string",
            "example": "current"
          },
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Snapshot id."
          },
          "state": {
            "type": "string",
            "enum": [
              "queued"
            ],
            "example": "queued"
          },
          "album_count": {
            "type": "integer",
            "description": "Albums the job will capture."
          },
          "estimated_cost_usd": {
            "type": "number",
            "description": "Scraper cost estimate before spend."
          }
        }
      },
      "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"
          }
        }
      },
      "ResearchMeasurementJobScope": {
        "type": "object",
        "description": "Provide exactly one of `catalog_id`, `album_ids`, or `isrcs`.",
        "properties": {
          "catalog_id": {
            "type": "string",
            "format": "uuid"
          },
          "album_ids": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "isrcs": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}
```