# Attach metadata to jobs

Tag jobs with custom key-value pairs for tracking and organization

"Tapestry" (a UGC platform like Bazaarvoice) processes thousands of user-submitted videos daily. Metadata lets you tag each job with your own IDs, labels, and context so you can match results back to your records.

## API

<CodeGroup labels={["CLI", "TypeScript", "Python", "curl"]}>
```bash
ittybit video \
  -i https://tapestry-app.com/submissions/video-9182.mov \
  --width 1280 \
  --format mp4
```

```typescript
const task = {
  input: 'https://tapestry-app.com/submissions/video-9182.mov',
  kind: 'video',
  options: {
    width: 1280,
    format: 'mp4',
  },
  metadata: {
    user_id: 'usr_abc123',
    submission_id: 'sub_9182',
    campaign: 'summer-launch',
  },
};

const res = await fetch('https://api.ittybit.com/jobs', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.ITTYBIT_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(task),
});
const data = await res.json();
```

```python

task = {
    "input": "https://tapestry-app.com/submissions/video-9182.mov",
    "kind": "video",
    "options": {
        "width": 1280,
        "format": "mp4",
    },
    "metadata": {
        "user_id": "usr_abc123",
        "submission_id": "sub_9182",
        "campaign": "summer-launch",
    },
}

res = requests.post(
    "https://api.ittybit.com/jobs",
    headers={"Authorization": f"Bearer {api_key}"},
    json=task,
)
data = res.json()
```

```bash
JOB='{
  "input": "https://tapestry-app.com/submissions/video-9182.mov",
  "kind": "video",
  "options": {
    "width": 1280,
    "format": "mp4"
  },
  "metadata": {
    "user_id": "usr_abc123",
    "submission_id": "sub_9182",
    "campaign": "summer-launch"
  }
}'

curl -X POST https://api.ittybit.com/jobs \
  -H "Authorization: Bearer $ITTYBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d "$JOB"
```

</CodeGroup>

The `metadata` object is returned in the job response and webhook payload. Use any string key-value pairs.

## Use cases

| Key        | Purpose                          |
| ---------- | -------------------------------- |
| `user_id`  | Match back to your user record   |
| `order_id` | Link to an e-commerce order      |
| `campaign` | Group jobs by marketing campaign |
| `source`   | Track where the upload came from |
| `priority` | Your own priority flag           |

## Metadata in webhooks

When the job completes, the metadata comes back in the webhook payload -- no extra lookup needed to figure out which user or record the result belongs to.

```json
{
  "id": "job_abc123",
  "status": "succeeded",
  "metadata": {
    "user_id": "usr_abc123",
    "submission_id": "sub_9182",
    "campaign": "summer-launch"
  },
  "output": {
    "url": "https://cdn.ittybit.com/..."
  }
}
```